GUÍA PARA DESARROLLADORES

Cómo enviar SMS desde Python con la API de Grupo Tecnophone

Envíe SMS desde sus scripts, servicios o aplicaciones Python con una petición HTTPS autenticada y una respuesta JSON fácil de procesar.

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

ElementoValor
MétodoPOST
Endpoint de producciónhttps://api.grupotecnophone.com/prod/v1/sms/send
Endpoint de sandboxhttps://api.grupotecnophone.com/test/v1/sms/send
EncabezadosAuthorization: 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
Respuestasid, status, encoding, num_chars, num_segments y error

Errores frecuentes

HTTPCódigoQué significa
400ENCRYPTION_REQUIREDLa conexión exige que to y body viajen cifrados con RSA-OAEP
400ENCRYPTION_NOT_ALLOWEDLa conexión opera en texto plano y se recibió contenido cifrado
400INPUT_PHONE_BLACKLISTEDEl número de destino está en lista negra
400INSUFFICIENT_BALANCESaldo 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.

Preguntas frecuentes: Enviar SMS con Python

Scroll al inicio