API SMS en México: guía para integrar el envío de mensajes en su sistema

Todo lo que un equipo de desarrollo necesita para integrar el envío de SMS desde su sistema: credenciales, endpoint, ambiente de pruebas, codificación de caracteres y manejo de errores.

Qué hace una API SMS y cuándo la necesita

Una API SMS es la interfaz que permite que un sistema envíe mensajes de texto de forma automática, sin intervención humana. Su plataforma de e-commerce, su core bancario, su CRM o su sistema de turnos hacen una petición HTTP, y el proveedor se encarga de que el mensaje llegue al teléfono del destinatario a través del operador móvil.

La necesita en cuanto el envío deja de ser una tarea manual: códigos OTP, alertas, confirmaciones, avisos de entrega, recordatorios. En cambio, para campañas masivas ocasionales suele bastar el panel web de la plataforma, que permite cargar una lista y programar el envío sin programar nada.

Paso 1: crear la conexión y obtener credenciales

En la plataforma de Grupo Tecnophone, la integración empieza en el panel web (app.grupotecnophone.com), en el menú Conexiones API → SMS. Al crear una conexión se genera un token Bearer, distinto para sandbox y para producción, y se configuran las direcciones IP desde las que se aceptarán peticiones. Ninguna solicitud se procesa si no llega con un token válido desde una IP autorizada.

En ese mismo lugar se define el modo de operación: texto plano, o cifrado activo, en el que los campos de destino y contenido viajan cifrados con RSA-OAEP-SHA256 y codificados en Base64. El cifrado es opcional, pero muy recomendable para banca y cualquier caso donde el contenido del mensaje sea sensible.

Paso 2: entender el endpoint de envío

El endpoint de producción es https://api.grupotecnophone.com/prod/v1/sms/send y el de sandbox es https://api.grupotecnophone.com/test/v1/sms/send. Ambos reciben una petición POST con un cuerpo JSON de dos campos obligatorios: to (número de destino) y body (texto del mensaje). Cada petición debe incluir los encabezados Authorization: Bearer {token} y un User-Agent identificable, que la plataforma usa para trazabilidad y detección de patrones anómalos.

{
  "to": "+5215512345678",
  "body": "Su pedido #48213 fue enviado. Llega mañana entre 10 y 14 h."
}

El número puede enviarse en formato internacional E.164 (con el signo + y el código de país) o como número nacional; si la conexión está asociada a un único país, la plataforma completa el prefijo automáticamente. La respuesta correcta devuelve un identificador único (sid), el estado, la codificación utilizada, el número de caracteres y la cantidad de segmentos.

{
  "sid": "sms_20251213164422_39bdafbd",
  "status": "success",
  "to": "+5215512345678",
  "encoding": "GSM7",
  "num_chars": 58,
  "num_segments": 1,
  "error": null
}

Paso 3: probar en sandbox antes de producción

El ambiente sandbox valida exactamente lo mismo que producción (token, IP, formato del payload, cifrado, reglas comerciales) pero no envía mensajes reales ni consume saldo. Es el lugar para probar la integración, los casos de error y el manejo de respuestas. Cuando todo funciona, pasar a producción consiste en cambiar el endpoint y el token; el código no cambia.

Un consejo práctico: guarde en su base de datos el sid de cada envío junto con el identificador de su propia operación (el pedido, la sesión, la alerta). Ese cruce es lo que le permitirá después reconciliar reportes de entrega y atender reclamos.

Codificación de caracteres y segmentos: lo que afecta el costo

Un SMS admite hasta 160 caracteres si usa el alfabeto GSM7 (letras sin acento, números y signos básicos) y solo 70 si necesita UCS-2, que es lo que ocurre en cuanto aparece un carácter fuera de ese alfabeto, como una ñ minúscula, ciertos acentos o emojis. Un mensaje más largo se divide en segmentos, y cada segmento se factura.

La plataforma determina la codificación automáticamente según el contenido y la configuración de la conexión: si solo está habilitado GSM7, los caracteres no soportados se normalizan a equivalentes compatibles; si está habilitado UCS-2, se usa GSM7 siempre que sea posible y UCS-2 solo cuando el texto lo requiere. La concatenación de segmentos también se controla desde la conexión; si está desactivada, el mensaje se limita a uno solo. Revisar el campo num_segments de la respuesta es la forma más sencilla de detectar mensajes que se están cobrando doble.

Manejo de errores y buenas prácticas

La API responde con códigos HTTP estándar: 200 cuando el mensaje fue aceptado, 400 ante errores de validación, cifrado o reglas comerciales, 401 si el token falta o es inválido, 403 si la IP no está autorizada y 500 ante un error interno. En los errores 400, el cuerpo incluye un código simbólico y numérico con su descripción; por ejemplo, INPUT_PHONE_BLACKLISTED (1205) cuando el número está en una lista de exclusión, INSUFFICIENT_BALANCE (8001) cuando una cuenta prepaga no tiene saldo, o ENCRYPTION_REQUIRED (1999) cuando la conexión exige cifrado y se envió texto plano.

• Reintente solo ante errores 500 o de red, con espera exponencial; nunca ante un 400, que se repetirá.
• Registre sid, código de error y timestamp de cada envío.
• Valide el formato del número antes de llamar a la API para no gastar peticiones.
• Use un User-Agent con el nombre de su aplicación y versión: facilita el soporte.
• Mantenga el token fuera del código fuente y rótelo periódicamente desde el panel.

La documentación oficial incluye ejemplos listos para copiar en cURL, PHP, Python, Node y Java, tanto en texto plano como con cifrado RSA. Encuéntrela en la sección de Desarrolladores del sitio.

Preguntas frecuentes