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 de su servidor registrada como autorizada para ese token.
- Un User-Agent que identifique a su aplicación, por ejemplo
MiEmpresa/1.0. - Python 3.8 o superior. El ejemplo usa la librería
requests(pip install requests); la documentación oficial incluye además un ejemplo solo con la biblioteca estándar.
Guarde el token en una variable de entorno (en estos ejemplos, GTP_SMS_TOKEN) y nunca lo incluya en el código de una app móvil o de un sitio web: las llamadas a la API deben salir siempre de su backend, desde una IP autorizada.
Enviar un SMS con Python
Esta función envía un SMS y devuelve la respuesta de la API, o lanza una excepción con el código de error:
import os
import requests
ENDPOINT = "https://api.grupotecnophone.com/prod/v1/sms/send"
TOKEN = os.environ["GTP_SMS_TOKEN"]
def send_sms(to: str, body: str) -> dict:
resp = requests.post(
ENDPOINT,
json={"to": to, "body": body},
headers={
"Authorization": f"Bearer {TOKEN}",
"User-Agent": "MiEmpresa/1.0",
},
timeout=30,
)
try:
data = resp.json()
except ValueError:
data = {}
if resp.status_code == 200 and data.get("status") == "success":
return data # sid, encoding, num_chars, num_segments
error = data.get("error") or {}
code = error.get("code", f"HTTP_{resp.status_code}")
raise RuntimeError(f"{code}: {error.get('message', resp.text)}")
if __name__ == "__main__":
result = send_sms("+525512345678", "Su codigo de verificacion es 482913. Vence en 5 minutos.")
print(result["sid"], result["num_segments"])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.
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.
Probar en sandbox
Cambie el endpoint por https://api.grupotecnophone.com/test/v1/sms/send 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.
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 incluye un ejemplo de cifrado RSA en PHP sin librerías externas.
Vea también la API SMS México, la conexión SMPP y las guías para PHP, Laravel, Node.js y Java. Si necesita credenciales de prueba, contáctenos.
