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. - Node.js 18 o superior (incluye
fetchnativo). En versiones anteriores puede usar el módulohttps, como en el ejemplo de la documentación oficial.
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 Node.js
Esta función envía un SMS y devuelve la respuesta, o lanza un error con el código recibido. Úsela siempre en el servidor, nunca en el navegador:
const ENDPOINT = 'https://api.grupotecnophone.com/prod/v1/sms/send';
async function sendSms(to, body) {
const res = await fetch(ENDPOINT, {
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.GTP_SMS_TOKEN}`,
'Content-Type': 'application/json',
'User-Agent': 'MiEmpresa/1.0',
},
body: JSON.stringify({ to, body }),
signal: AbortSignal.timeout(30_000),
});
const data = await res.json().catch(() => ({}));
if (res.ok && data.status === 'success') {
return data; // sid, encoding, num_chars, num_segments
}
const code = data.error?.code ?? `HTTP_${res.status}`;
throw new Error(`${code}: ${data.error?.message ?? res.statusText}`);
}
sendSms('+525512345678', 'Su codigo de verificacion es 482913. Vence en 5 minutos.')
.then((r) => console.log(r.sid, r.num_segments))
.catch((err) => console.error(err.message));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, Python y Java. Si necesita credenciales de prueba, contáctenos.
