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.
Enviar SMS a varios destinatarios con Python
Para enviar SMS masivos desde Python basta con recorrer su lista y llamar a la misma función send_sms del ejemplo anterior. Guarde el sid de cada envío y separe los números con error para revisarlos después.
import time
destinatarios = ["+525512345678", "+525598765432", "+523312345678"]
mensaje = "Su pedido 1234 ya va en camino. Gracias por su compra."
enviados, fallidos = [], []
for numero in destinatarios:
try:
r = send_sms(numero, mensaje)
enviados.append((numero, r["sid"]))
except RuntimeError as e:
fallidos.append((numero, str(e)))
time.sleep(0.1) # ritmo moderado para listas grandes
print(f"{len(enviados)} enviados, {len(fallidos)} con error")
Para listas de miles de números conviene procesar en lotes y reintentar solo los errores temporales. Si prefiere no programar, también puede enviar SMS masivos desde Excel o CSV en el panel de la plataforma.
Enviar un código OTP con Python
Un caso muy común es mandar un código de verificación. Genere el código con el módulo secrets (no con random), envíelo por SMS y guarde solo su hash con fecha de vencimiento.
import secrets
def enviar_otp(numero: str) -> str:
codigo = f"{secrets.randbelow(10**6):06d}" # 6 dígitos con generador seguro
send_sms(numero, f"Su codigo de verificacion es {codigo}. Vence en 5 minutos. No lo comparta.")
return codigo # guárdelo con hash y fecha de vencimiento, nunca en texto plano
Vea cómo diseñar el flujo completo, los tiempos de vencimiento y los reintentos en nuestra guía de autenticación OTP por SMS.
Enviar SMS con Python sin librerías externas
Si no puede instalar paquetes en el servidor, la biblioteca estándar alcanza: urllib.request hace la misma petición sin dependencias.
import json
import os
import urllib.error
import urllib.request
req = urllib.request.Request(
"https://api.grupotecnophone.com/prod/v1/sms/send",
data=json.dumps({"to": "+525512345678", "body": "Su cita es manana a las 10:00."}).encode("utf-8"),
headers={
"Authorization": "Bearer " + os.environ["GTP_SMS_TOKEN"],
"Content-Type": "application/json",
"User-Agent": "MiEmpresa/1.0",
},
method="POST",
)
try:
with urllib.request.urlopen(req, timeout=30) as resp:
data = json.load(resp)
except urllib.error.HTTPError as e:
# 400, 401, 403 y 500 llegan aqui; el cuerpo trae el objeto error
data = json.loads(e.read() or b"{}")
except urllib.error.URLError as e:
raise SystemExit("Error de red: " + str(e.reason))
if data.get("status") == "success":
print("Enviado. SID:", data["sid"])
else:
print("No enviado:", (data.get("error") or {}).get("code", "sin detalle"))
A diferencia de requests, urllib lanza una excepción en los errores HTTP; por eso el ejemplo lee el cuerpo de la respuesta dentro del except.
Resumen de la petición
| Elemento | Valor |
|---|---|
| Método | POST |
| Endpoint de producción | https://api.grupotecnophone.com/prod/v1/sms/send |
| Endpoint de sandbox | https://api.grupotecnophone.com/test/v1/sms/send |
| Encabezados | Authorization: Bearer con su token, Content-Type: application/json y User-Agent |
| Cuerpo (JSON) | to: número de destino con código de país; body: texto del mensaje |
| Respuesta | sid, status, encoding, num_chars, num_segments y error |
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, Java, C# (.NET) y cURL. Si necesita credenciales de prueba, contáctenos.


