Enviar SMS con Node.js y la API de 360nrs | Guía, código y ejemplos

APIs

Enviar SMS desde una aplicación web o backend es una funcionalidad clave para notificaciones, alertas y campañas de marketing. Node.js, con su capacidad para manejar múltiples solicitudes de manera eficiente, es una excelente opción para este tipo de tareas.

Al final de este tutorial, podrás:

Enviar SMS desde Node.js a través de la API de 360NRS.
Manejar respuestas de la API y errores de envío.
Usar parámetros avanzados como envío programado y variables dinámicas.

¡Vamos allá!

Requisitos para enviar SMS con Node.js

Antes de comenzar, asegúrate de cumplir con los siguientes requisitos:

🔹 Cuenta en 360NRS: Si aún no tienes una, regístrate en 360NRS.
🔹 Obtener el Token de Autenticación: Lo necesitas para autenticarte en la API.
🔹 Node.js instalado: Puedes descargarlo desde nodejs.org.

Configuración del entorno en Node.js

Paso 1: Crear un nuevo proyecto en Node.js

Si aún no tienes un proyecto, créalo ejecutando:

mkdir enviar-sms-node
cd enviar-sms-node
npm init -y

Esto creará un archivo package.json con la configuración básica del proyecto.

Paso 2: Instalar Axios

Axios es una librería que facilita la realización de solicitudes HTTP. Instálala con:

npm install axios

Código para enviar SMS con Node.js

A continuación, te mostramos cómo enviar un SMS utilizando la API de 360NRS.

Código para enviar un SMS

 var axios = require('axios');

var config = {
  method: 'post',
  url: 'https://dashboard.360nrs.com/api/rest/sms',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Basic YOUR_AUTH_TOKEN' // Reemplaza con tu token de autenticación
  },
  data: JSON.stringify({
    "to": ["34666555444"], // Número de teléfono en formato internacional
    "from": "TEST", // Remitente del SMS
    "message": "SMS text message" // Texto del mensaje
  })
};

axios(config)
.then(function (response) {
  console.log("SMS enviado con éxito:", response.data);
})
.catch(function (error) {
  console.error("Error al enviar SMS:", error.response ? error.response.data : error.message);
});

Explicación del código

✔️ Se usa Axios para hacer una solicitud HTTP POST a la API.
✔️ El Authorization usa un token Basic Auth, reemplázalo con tu TOKEN REAL.
✔️ to: Número de teléfono del destinatario en formato internacional.
✔️ from: Remitente (puede ser un número o texto alfanumérico de hasta 11 caracteres).
✔️ message: Contenido del SMS.

Si todo está correcto, recibirás una respuesta con el código 202 ACCEPTED y detalles del SMS enviado.

Manejo de respuestas de la API

La API de 360NRS devuelve diferentes respuestas dependiendo del estado del mensaje. Aquí te mostramos los principales casos:

Respuesta Exitosa (202 ACCEPTED)

{
  "campaignId": 100000,
  "sendingId": 100001,
  "result": [
    {
      "accepted": true,
      "to": "34666555444",
      "id": "XXXXXXXXXXXXX",
      "parts": 1
    }
  ]
}

🔹 Significado: El SMS fue aceptado y está en proceso de envío.

Error Parcial (207 MULTI-STATUS)

{
  "campaignId": 100000,
  "sendingId": 100001,
  "result": [
    {
      "accepted": true,
      "to": "34666555444",
      "id": "XXXXXXXXXXXXX"
    },
    {
      "accepted": false,
      "to": "34",
      "error": {
        "code": 102,
        "description": "No valid recipients"
      }
    }
  ]
}

🔹 Significado: Algunos SMS se enviaron correctamente y otros fallaron.

Error en el envío (400 BAD REQUEST)

{
  "error": {
    "code": 102,
    "description": "No valid recipients"
  }
}

🔹 Solución: Verifica que los números de teléfono sean correctos.

Parámetros avanzados en el envío de SMS con Node.js

La API permite personalizar los envíos con parámetros adicionales:

Programar el envío de un SMS con Node.js

{
  "to": ["34666555444"],
  "from": "TEST",
  "message": "Mensaje programado",
  "scheduleDate": "20250215142000" 
}

📅 Esto enviará el SMS el 15 de febrero de 2025 a las 14:20:00 UTC.

Mensajes con variables personalizadas

{
  "to": ["34666555444"],
  "from": "TEST",
  "message": "Hola {name}",
  "sub": [
    { "name": "Juan" }
  ]
}

📝 El receptor verá: "Hola Juan"

Consultar el estado de un SMS enviado

Puedes verificar el estado de un mensaje enviando una solicitud GET con su ID.

Código en Node.js

 var axios = require('axios');

var config = {
  method: 'get',
  url: 'https://dashboard.360nrs.com/api/rest/sms/XXXXXXXXXXXXX', // Reemplaza con el ID del SMS
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Basic YOUR_AUTH_TOKEN'
  }
};

axios(config)
.then(function (response) {
  console.log("Estado del SMS:", response.data);
})
.catch(function (error) {
  console.error("Error al consultar SMS:", error.response ? error.response.data : error.message);
});

Buenas prácticas en el uso de la API SMS con Node.js

Cuando trabajamos con APIs de terceros, especialmente aquellas que manejan datos sensibles como el envío de SMS, es importante seguir ciertas buenas prácticas para garantizar seguridad, estabilidad y eficiencia en nuestras aplicaciones.

Aquí te explicamos por qué cada una de estas prácticas es esencial y cómo aplicarlas correctamente.

1. Nunca compartas tu Authorization Token en código público

El Authorization Token es una credencial privada que te permite autenticarte en la API de 360NRS y realizar envíos de SMS. Si este token cae en manos equivocadas, cualquiera podría enviar mensajes a través de tu cuenta, generando costos no autorizados y potencialmente dañando tu reputación.

🔹 Errores comunes
❌ Subir tu código a un repositorio público (GitHub, GitLab, Bitbucket) sin ocultar el token.
❌ Incluir el token directamente en el código como un string (hardcoded).
❌ Compartir el token en foros o documentación sin darse cuenta.

🔹 Cómo proteger tu token correctamente

✅ Usa variables de entorno (.env)
Almacenar credenciales en un archivo .env es una práctica estándar para evitar exponer datos sensibles en el código fuente.

1️⃣ Instala dotenv para manejar variables de entorno:

npm install dotenv

2️⃣ Crea un archivo .env en la raíz de tu proyecto y agrega tu token:

AUTH_TOKEN=TU_TOKEN_AQUI

3️⃣ En tu código, carga el token desde el archivo .env:

require('dotenv').config();

var axios = require('axios');

var config = {
  method: 'post',
  url: 'https://dashboard.360nrs.com/api/rest/sms',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Basic ${process.env.AUTH_TOKEN}`
  },
  data: JSON.stringify({
    "to": ["34666555444"],
    "from": "TEST",
    "message": "Mensaje seguro"
  })
};

axios(config)
.then(response => console.log("SMS enviado con éxito:", response.data))
.catch(error => console.error("Error al enviar SMS:", error.message));

✅ Usa variables de entorno en servicios cloud
Si despliegas tu aplicación en Heroku, Vercel, AWS o cualquier otro servicio, puedes definir las variables de entorno desde la configuración de la plataforma sin necesidad de un archivo .env.

📌 Regla de oro: Nunca subas archivos .env al repositorio. Agrega .env al archivo .gitignore para evitar exponerlo accidentalmente.

echo .env >> .gitignore

2. Maneja correctamente los errores y reintenta en caso de fallo

Cuando envías un SMS, la API de 360NRS puede responder con diferentes códigos de estado dependiendo del resultado del envío. Manejar estos errores correctamente evita que tu aplicación falle y ayuda a mejorar la experiencia del usuario.

🔹 Ejemplo de errores comunes

Código HTTP	Significado	Posible solución
`400 Bad Request`	Alguno de los parámetros es incorrecto.	Verifica que el número tenga el formato correcto.
`401 Unauthorized`	Token de autenticación incorrecto o caducado.	Asegúrate de usar el token correcto en el encabezado.
`429 Too Many Requests`	Se ha excedido el límite de solicitudes.	Implementa una estrategia de reintento con tiempo de espera.
`500 Internal Server Error`	Error en el servidor de 360NRS.	Reintenta después de unos segundos.

🔹 Cómo manejar errores correctamente

Captura los errores y muestra mensajes adecuados

 axios(config)
  .then(response => {
    console.log("SMS enviado con éxito:", response.data);
  })
  .catch(error => {
    if (error.response) {
      console.error("Error en el envío:", error.response.data);
    } else if (error.request) {
      console.error("No hubo respuesta del servidor:", error.request);
    } else {
      console.error("Error desconocido:", error.message);
    }
  });

Implementa un sistema de reintento para fallos temporales

Si recibimos un error 500 o 429, podemos reintentar el envío después de un breve tiempo de espera.

 const enviarSMS = async (intentos = 3) => {
  for (let i = 0; i < intentos; i++) {
    try {
      let response = await axios(config);
      console.log("SMS enviado con éxito:", response.data);
      return;
    } catch (error) {
      console.error(`Intento ${i + 1} fallido:`, error.message);
      if (i < intentos - 1) {
        console.log("Reintentando en 5 segundos...");
        await new Promise(resolve => setTimeout(resolve, 5000));
      } else {
        console.error("No se pudo enviar el SMS después de varios intentos.");
      }
    }
  }
};

enviarSMS();

📌 Esto asegura que no abandonemos el proceso al primer fallo y permite recuperar errores temporales automáticamente.

3. Valida los números de teléfono antes de enviarlos

La API de 360NRS requiere que los números de teléfono estén en formato internacional, lo que significa que deben incluir el prefijo del país (Ejemplo para España: +34).

🔹 Errores comunes
❌ Enviar números sin prefijo (666555444 en lugar de 34666555444).
❌ Usar caracteres no numéricos.
❌ Números de teléfono mal formateados.

🔹 Cómo validar un número antes de enviarlo

 const validarNumero = (numero) => {
  const regex = /^\d{10,15}$/; // Acepta entre 10 y 15 dígitos
  return regex.test(numero);
};

const numero = "34666555444";

if (validarNumero(numero)) {
  console.log("Número válido. Procediendo con el envío...");
} else {
  console.error("Número inválido. Verifica el formato.");
}

📌 Implementar validaciones previas evita fallos en la API y mejora la eficiencia.

Próximos pasos

Ahora que ya sabes cómo enviar SMS con Node.js y la API de 360NRS, estos son algunos próximos pasos para mejorar tu integración:

Experimenta con parámetros avanzados

Usa scheduleDate para programar envíos.
Implementa sub para personalizar mensajes dinámicamente.

Automatiza envíos con bases de datos

Conecta tu aplicación a MySQL, PostgreSQL o MongoDB.
Envía SMS automáticamente a clientes o usuarios desde tu base de datos.

Integra el seguimiento de entrega en tu sistema

Usa la API GET https://dashboard.360nrs.com/api/rest/sms/<ID> para consultar el estado de un SMS.
Almacena la información en una base de datos para auditoría.

Con estas mejoras, tu integración de SMS será más robusta y eficiente. ¡Manos a la obra!

Jaime Martínez

Jaime Martínez – Product Manager 360NRS

Jaime Martínez, Product Manager en 360NRS, experto en comunicaciones móviles, marketing online, diseño, usabilidad y gestión de producto. Con más de 20 años de experiencia en el sector, Jaime ha liderado el desarrollo y evolución de productos digitales, impulsando estrategias centradas en el usuario que optimizan tanto la experiencia como el rendimiento de las soluciones. Su amplia trayectoria en diseño, marketing digital y gestión de producto aporta una visión estratégica clave para la innovación y el éxito de nuestras soluciones multicanal.

Enviar SMS con Node.js