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.
Enviar SMS a varios destinatarios con Node.js
Para enviar SMS masivos desde Node.js reutilice la función sendSms del ejemplo anterior y recorra su lista. Enviar uno por uno con una pausa corta evita picos y facilita registrar el sid o el error de cada número.
const destinatarios = ["+525512345678", "+525598765432"];
const mensaje = "Su pedido 1234 ya va en camino.";
const pausa = (ms) => new Promise((r) => setTimeout(r, ms));
for (const numero of destinatarios) {
try {
const r = await sendSms(numero, mensaje);
console.log(numero, "->", r.sid);
} catch (err) {
console.error(numero, "-> error:", err.message);
}
await pausa(100); // ritmo moderado para listas grandes
}
Sin programar, también puede enviar SMS masivos desde Excel o CSV.
Enviar un código OTP con Node.js
Use crypto.randomInt, que es seguro para códigos de verificación, y guarde solo el hash del código.
import { randomInt } from "node:crypto";
const codigo = String(randomInt(0, 1_000_000)).padStart(6, "0");
await sendSms("+525512345678", `Su codigo de verificacion es ${codigo}. Vence en 5 minutos.`);
// Guarde solo el hash del código y su fecha de vencimiento
Más detalles del flujo en la guía de autenticación OTP por SMS.
Enviar SMS con Node.js usando axios
Si su proyecto ya usa axios, la petición es la misma. Instálelo con npm install axios; el ejemplo usa módulos ES (archivo .mjs o "type": "module" en package.json):
import axios from 'axios';
const client = axios.create({
baseURL: 'https://api.grupotecnophone.com/prod/v1',
timeout: 30000,
validateStatus: () => true, // permite leer tambien las respuestas 4xx y 5xx
headers: {
Authorization: 'Bearer ' + process.env.GTP_SMS_TOKEN,
'User-Agent': 'MiEmpresa/1.0',
},
});
try {
const { status, data } = await client.post('/sms/send', {
to: '+525512345678',
body: 'Su pedido 1234 ya va en camino.',
});
if (status === 200 && data.status === 'success') {
console.log('Enviado. SID: ' + data.sid);
} else {
console.log('No enviado: ' + (data?.error?.code ?? 'HTTP_' + status));
}
} catch (err) {
console.error('Error de red: ' + err.message);
}
Con validateStatus devolviendo true, axios no lanza una excepción en los errores 400, 401 o 403, y su código puede leer el objeto error de la respuesta.
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, Python, Java, C# (.NET) y cURL. Si necesita credenciales de prueba, contáctenos.


