Antes de empezar
- Una conexión API creada en el panel web (app.grupotecnophone.com), con su Bearer Token de sandbox o de producción.
- La IP pública del equipo o servidor desde el que ejecuta cURL, registrada como autorizada para ese token.
- Un User-Agent que identifique a su aplicación, por ejemplo MiEmpresa/1.0.
- cURL, que ya viene instalado en Linux, macOS y Windows 10 o superior. Para leer la respuesta en los scripts usamos jq, que es opcional.
Guarde el token en una variable de entorno (en estos ejemplos, GTP_SMS_TOKEN) para que no quede escrito en sus scripts. En Windows use curl.exe y guarde el JSON en un archivo (-d @sms.json) para evitar problemas con las comillas.
Enviar un SMS con cURL
Este comando envía un SMS y, al final, muestra el código HTTP de la respuesta:
curl -sS https://api.grupotecnophone.com/prod/v1/sms/send \
-H "Authorization: Bearer $GTP_SMS_TOKEN" \
-H "Content-Type: application/json" \
-H "User-Agent: MiEmpresa/1.0" \
--max-time 30 \
-w "\nHTTP %{http_code}\n" \
-d '{"to":"+525512345678","body":"Su codigo de verificacion es 482913. Vence en 5 minutos."}'Es la forma más rápida de comprobar que el token, la IP autorizada y el formato del mensaje están bien antes de integrar la API en su aplicación.
Respuesta de la API
Si el mensaje fue aceptado, la API responde con HTTP 200 y un JSON como este:
{
"sid": "sms_20261012143201_39bdafbd",
"status": "success",
"to": "+525512345678",
"body": "Su codigo de verificacion es 482913. Vence en 5 minutos.",
"encoding": "GSM7",
"num_chars": 56,
"num_segments": 1,
"error": null
}Guarde el sid: es el identificador con el que podrá conciliar el reporte de entrega del mensaje. El campo num_segments indica cuántos segmentos se cobrarán; vea cómo se calculan los segmentos.
Enviar SMS a varios destinatarios desde la terminal
Para una lista corta puede recorrer un archivo de números con un script de Bash. El script muestra el sid de cada mensaje o el código de error:
#!/usr/bin/env bash
# destinatarios.txt: un número por línea, en formato +52...
while IFS= read -r numero; do
respuesta=$(curl -sS https://api.grupotecnophone.com/prod/v1/sms/send \
-H "Authorization: Bearer $GTP_SMS_TOKEN" \
-H "Content-Type: application/json" \
-H "User-Agent: MiEmpresa/1.0" \
--max-time 30 \
-d "{\"to\":\"$numero\",\"body\":\"Su pedido fue enviado. Gracias por su compra.\"}")
echo "$numero $(echo "$respuesta" | jq -r '.sid // .error.code')"
sleep 0.2
done < destinatarios.txtPara volúmenes altos o envíos recurrentes, integre la API desde su aplicación con una cola de envíos. Sin programar, también puede enviar SMS masivos desde Excel o CSV.
Probar en sandbox con cURL
Cambie el endpoint por el de sandbox y use el token de sandbox. Ese entorno valida token, IP, payload y cifrado con la misma lógica que producción, pero no envía SMS reales:
curl -sS https://api.grupotecnophone.com/test/v1/sms/send \
-H "Authorization: Bearer $GTP_SMS_TOKEN_SANDBOX" \
-H "Content-Type: application/json" \
-H "User-Agent: MiEmpresa/1.0" \
-d '{"to":"+525512345678","body":"Mensaje de prueba"}'Errores frecuentes
| HTTP | Código | Qué significa |
|---|---|---|
| 400 | ENCRYPTION_REQUIRED | La conexión exige que to y body viajen cifrados con RSA-OAEP |
| 400 | ENCRYPTION_NOT_ALLOWED | La conexión opera en texto plano y se recibió contenido cifrado |
| 400 | INPUT_PHONE_BLACKLISTED | El número de destino está en lista negra |
| 400 | INSUFFICIENT_BALANCE | Saldo insuficiente para el envío |
| 401 | — | Token ausente o inválido |
| 403 | — | La IP de origen no está autorizada para el token |
| 500 | — | Error interno no esperado |
En los errores 400 la respuesta incluye un objeto error con code, code_num y message.
Del comando a su aplicación
El comando de cURL tiene las mismas partes que cualquier integración: el endpoint, el encabezado Authorization con el Bearer Token, el User-Agent y un JSON con to y body. Cuando la prueba funcione, lleve esa misma petición al lenguaje de su backend con nuestras guías para PHP, Laravel, Python, Node.js, Java y C# (.NET).
Buenas prácticas
- Defina un timeout y registre cada respuesta con su
sid. - Ante un error de red sin respuesta, no reenvíe a ciegas: verifique primero para no duplicar el mensaje al usuario.
- Reintente solo errores 500, con espera progresiva y un número máximo de intentos.
- Encole los envíos masivos en lugar de enviarlos en el ciclo de una petición web.
- Si el contenido es sensible, active el cifrado de la conexión; la documentación de la API describe el formato de cifrado RSA-OAEP.
Vea también la API SMS México, la conexión SMPP y las guías para PHP, Laravel, Python, Node.js, Java y C# (.NET). Si necesita credenciales de prueba, contáctenos.
