Cómo enviar SMS con Java utilizando la API de 360nrs

El envío de SMS es una funcionalidad clave para muchas aplicaciones que buscan comunicarse de forma directa y efectiva con sus usuarios.

Gracias a la API de 360nrs, puedes integrar esta capacidad en tus proyectos escritos en Java de manera sencilla y eficiente.

En este artículo, exploraremos cómo realizar el envío de SMS utilizando Java con ejemplos prácticos y detallaremos los parámetros más importantes de la API.

---

Introducción a la API de SMS de 360nrs

La API de 360nrs permite el envío de SMS mediante solicitudes HTTP POST a una URL específica. Para garantizar la seguridad, utiliza autenticación mediante tokens. En el siguiente ejemplo práctico, veremos cómo enviar un SMS y gestionar respuestas del servidor, incluyendo mensajes aceptados, errores y detalles adicionales.

---

Ejemplo: Enviar un SMS con Java

Este ejemplo muestra cómo configurar una solicitud HTTP POST para enviar un SMS mediante la API de 360nrs.

Código de ejemplo

Descripción: El código se conecta al endpoint de la API, envía los datos necesarios en formato JSON y procesa la respuesta.

import java.io.DataOutputStream;
import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.URL;
import java.net.HttpsURLConnection;

public class App {
    public static void main(String[] args) {
        try {
            // Definir la URL de la API
            URL url = new URL("https://dashboard.360nrs.com/api/rest/sms");
            HttpsURLConnection connection = (HttpsURLConnection) url.openConnection();
            
            // Configuración de la solicitud HTTP
            connection.setRequestMethod("POST");
            connection.setRequestProperty("Authorization", "Basic YOUR_AUTH_TOKEN");
            connection.setRequestProperty("Accept", "application/json");
            
            // Cuerpo de la solicitud
            String requestBody = "{ \"to\": [\"34666555444\"], \"from\": \"TEST\", \"message\": \"SMS text message\" }";
            
            // Enviar la solicitud
            connection.setDoOutput(true);
            DataOutputStream wr = new DataOutputStream(connection.getOutputStream());
            wr.writeBytes(requestBody);
            wr.flush();
            wr.close();
            
            // Leer la respuesta
            BufferedReader in = new BufferedReader(new InputStreamReader(connection.getInputStream()));
            String inputLine;
            StringBuffer response = new StringBuffer();
            
            while ((inputLine = in.readLine()) != null) {
                response.append(inputLine);
            }
            in.close();
            
            // Imprimir la respuesta
            System.out.println(response.toString());
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

---

Respuestas posibles del servidor

Respuesta exitosa (HTTP 202)

Cuando el mensaje se envía correctamente, la API devuelve el código 202 (ACCEPTED) junto con un JSON detallado.

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

Respuesta parcial (HTTP 207)

Si algunos mensajes fallan, el código 207 (MULTI-STATUS) proporciona detalles sobre los números aceptados y los rechazados.

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

Respuesta de error (HTTP 400)

Si la solicitud contiene errores, se devuelve un mensaje de error con detalles.

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

---

Parámetros de la solicitud

A continuación, se explican los principales parámetros que puedes utilizar en la solicitud:

Parámetro	Tipo	Obligatorio	Descripción
message	string	Sí	Texto del mensaje (máximo 160 caracteres para mensajes no multiparte).
to	array	Sí	Número(s) de teléfono de destino, con prefijo internacional (Ejemplo: 34666666666).
from	string	Sí	Remitente del mensaje (máximo 15 números o 11 caracteres alfanuméricos).
encoding	string	No	Codificación del mensaje: gsm (default) o utf-16.
scheduleDate	string	No	Fecha y hora programada para el envío en formato UTC (YYYYMMDDHHMMSS).
parts	integer	No	Número máximo de partes del mensaje. Default: 1.
campaignName	string	No	Nombre de la campaña asociada al envío.
notificationUrl	string/array	No	URL donde se recibirán notificaciones de entrega.
certified	boolean	No	Define si el SMS es certificado (coste adicional).
otpConfig	object	No	Configuración para códigos OTP, incluyendo longitud, alfanumérico y validez.

---

Consideraciones importantes

1. Autenticación: Reemplaza "YOUR_AUTH_TOKEN" con tu token de autenticación proporcionado por 360nrs.
2. Formato de números: Asegúrate de incluir el prefijo internacional para todos los números de teléfono.
3. Codificación: Si usas caracteres especiales o mensajes largos, configura adecuadamente el parámetro encoding.
4. Errores comunes: Revisa cuidadosamente los errores devueltos para realizar ajustes en los parámetros de la solicitud.

Ejemplos prácticos de implementación de SMS con Java

A continuación, te presentamos varios ejemplos prácticos para diferentes escenarios comunes al implementar el envío de SMS con Java utilizando la API de 360nrs. Cada caso incluye el código necesario y una breve descripción de su funcionalidad.

---

Enviar un SMS básico a un único destinatario

Descripción: Este ejemplo envía un mensaje sencillo a un único número de teléfono.

import java.io.DataOutputStream;
import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.URL;
import java.net.HttpsURLConnection;

public class SingleSMS {
    public static void main(String[] args) {
        try {
            URL url = new URL("https://dashboard.360nrs.com/api/rest/sms");
            HttpsURLConnection connection = (HttpsURLConnection) url.openConnection();
            connection.setRequestMethod("POST");
            connection.setRequestProperty("Authorization", "Basic YOUR_AUTH_TOKEN");
            connection.setRequestProperty("Accept", "application/json");
            
            // Cuerpo de la solicitud
            String requestBody = "{ \"to\": [\"34666555444\"], \"from\": \"TEST\", \"message\": \"Hola, este es un mensaje de prueba\" }";
            connection.setDoOutput(true);
            DataOutputStream wr = new DataOutputStream(connection.getOutputStream());
            wr.writeBytes(requestBody);
            wr.flush();
            wr.close();
            
            // Leer la respuesta
            BufferedReader in = new BufferedReader(new InputStreamReader(connection.getInputStream()));
            String inputLine;
            StringBuffer response = new StringBuffer();
            while ((inputLine = in.readLine()) != null) {
                response.append(inputLine);
            }
            in.close();
            
            System.out.println("Respuesta del servidor: " + response.toString());
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

---

2. Enviar un SMS a múltiples destinatarios

Descripción: Este ejemplo envía el mismo mensaje a varios números de teléfono.

public class MultiRecipientSMS {
    public static void main(String[] args) {
        try {
            URL url = new URL("https://dashboard.360nrs.com/api/rest/sms");
            HttpsURLConnection connection = (HttpsURLConnection) url.openConnection();
            connection.setRequestMethod("POST");
            connection.setRequestProperty("Authorization", "Basic YOUR_AUTH_TOKEN");
            connection.setRequestProperty("Accept", "application/json");
            
            // Cuerpo de la solicitud con múltiples destinatarios
            String requestBody = "{ \"to\": [\"34666555444\", \"34666777888\"], \"from\": \"TEST\", \"message\": \"Mensaje para múltiples destinatarios\" }";
            connection.setDoOutput(true);
            DataOutputStream wr = new DataOutputStream(connection.getOutputStream());
            wr.writeBytes(requestBody);
            wr.flush();
            wr.close();
            
            BufferedReader in = new BufferedReader(new InputStreamReader(connection.getInputStream()));
            String inputLine;
            StringBuffer response = new StringBuffer();
            while ((inputLine = in.readLine()) != null) {
                response.append(inputLine);
            }
            in.close();
            
            System.out.println("Respuesta del servidor: " + response.toString());
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

---

3. Enviar un SMS programado

Descripción: Programa el envío de un mensaje para una fecha y hora específica en formato UTC.

public class ScheduledSMS {
    public static void main(String[] args) {
        try {
            URL url = new URL("https://dashboard.360nrs.com/api/rest/sms");
            HttpsURLConnection connection = (HttpsURLConnection) url.openConnection();
            connection.setRequestMethod("POST");
            connection.setRequestProperty("Authorization", "Basic YOUR_AUTH_TOKEN");
            connection.setRequestProperty("Accept", "application/json");
            
            // Programar un SMS
            String requestBody = "{ \"to\": [\"34666555444\"], \"from\": \"TEST\", \"message\": \"Mensaje programado\", \"scheduleDate\": \"20231130143000\" }";
            connection.setDoOutput(true);
            DataOutputStream wr = new DataOutputStream(connection.getOutputStream());
            wr.writeBytes(requestBody);
            wr.flush();
            wr.close();
            
            BufferedReader in = new BufferedReader(new InputStreamReader(connection.getInputStream()));
            String inputLine;
            StringBuffer response = new StringBuffer();
            while ((inputLine = in.readLine()) != null) {
                response.append(inputLine);
            }
            in.close();
            
            System.out.println("Respuesta del servidor: " + response.toString());
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

---

4. Enviar un SMS con un mensaje largo (multiparte)

Descripción: Divide un mensaje largo en varias partes automáticamente. Se debe especificar el número máximo de partes permitidas.

public class MultipartSMS {
    public static void main(String[] args) {
        try {
            URL url = new URL("https://dashboard.360nrs.com/api/rest/sms");
            HttpsURLConnection connection = (HttpsURLConnection) url.openConnection();
            connection.setRequestMethod("POST");
            connection.setRequestProperty("Authorization", "Basic YOUR_AUTH_TOKEN");
            connection.setRequestProperty("Accept", "application/json");
            
            // Mensaje largo que se dividirá en múltiples partes
            String requestBody = "{ \"to\": [\"34666555444\"], \"from\": \"TEST\", \"message\": \"Este es un mensaje muy largo que requiere ser dividido en múltiples partes automáticamente.\", \"parts\": 3 }";
            connection.setDoOutput(true);
            DataOutputStream wr = new DataOutputStream(connection.getOutputStream());
            wr.writeBytes(requestBody);
            wr.flush();
            wr.close();
            
            BufferedReader in = new BufferedReader(new InputStreamReader(connection.getInputStream()));
            String inputLine;
            StringBuffer response = new StringBuffer();
            while ((inputLine = in.readLine()) != null) {
                response.append(inputLine);
            }
            in.close();
            
            System.out.println("Respuesta del servidor: " + response.toString());
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

---

5. Enviar un SMS con una URL de notificación

Descripción: Recibe actualizaciones sobre el estado de entrega del SMS en una URL específica.

public class SMSWithNotification {
    public static void main(String[] args) {
        try {
            URL url = new URL("https://dashboard.360nrs.com/api/rest/sms");
            HttpsURLConnection connection = (HttpsURLConnection) url.openConnection();
            connection.setRequestMethod("POST");
            connection.setRequestProperty("Authorization", "Basic YOUR_AUTH_TOKEN");
            connection.setRequestProperty("Accept", "application/json");
            
            // Notificación de entrega en una URL específica
            String requestBody = "{ \"to\": [\"34666555444\"], \"from\": \"TEST\", \"message\": \"Mensaje con notificación\", \"notificationUrl\": \"https://miweb.com/sms-notification\" }";
            connection.setDoOutput(true);
            DataOutputStream wr = new DataOutputStream(connection.getOutputStream());
            wr.writeBytes(requestBody);
            wr.flush();
            wr.close();
            
            BufferedReader in = new BufferedReader(new InputStreamReader(connection.getInputStream()));
            String inputLine;
            StringBuffer response = new StringBuffer();
            while ((inputLine = in.readLine()) != null) {
                response.append(inputLine);
            }
            in.close();
            
            System.out.println("Respuesta del servidor: " + response.toString());
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

---

Estos ejemplos cubren distintos escenarios que puedes adaptar fácilmente según tus necesidades. Cada implementación muestra cómo aprovechar las funcionalidades avanzadas de la API de 360nrs para gestionar el envío de SMS con Java.

Ejemplos de servicios y aplicaciones

Ejemplos de servicios y aplicaciones donde la integración de SMS y JAVA puede ser útil.

1. Notificaciones de alertas en sistemas de monitoreo

Aplicación: Servicios como Nagios, Zabbix o sistemas personalizados de monitoreo pueden integrar el envío de SMS para alertar sobre problemas críticos en servidores, aplicaciones o infraestructura.

Caso de uso:

• Un servidor se desconecta.
• Se detecta un uso elevado de CPU o RAM.
• Fallos en bases de datos o aplicaciones críticas.

Con la integración de SMS, los administradores recibirán alertas inmediatas en sus dispositivos móviles, garantizando una acción rápida.

---

2. Recordatorios y confirmaciones en sistemas médicos

Aplicación: Clínicas, hospitales o aplicaciones de gestión médica pueden utilizar SMS para recordar citas médicas o confirmar asistencias.

Caso de uso:

• Recordatorios automáticos de consultas médicas programadas.
• Confirmaciones de reserva enviadas al paciente.
• Envío de resultados médicos o alertas personalizadas, respetando la privacidad del usuario.

Esto reduce significativamente las ausencias a citas y mejora la comunicación con los pacientes.

---

3. Autenticación de dos factores (2FA)

Aplicación: Plataformas de comercio electrónico, bancos y aplicaciones web pueden usar SMS para reforzar la seguridad mediante códigos OTP (One-Time Password).

Caso de uso:

• Un usuario intenta iniciar sesión en una cuenta sensible.
• El sistema genera un código único enviado por SMS para verificar la identidad del usuario.
• Esto aumenta la seguridad frente a accesos no autorizados.

Los códigos OTP también son útiles para validar transacciones financieras y cambios de contraseñas.

---

4. Marketing y promociones

Aplicación: Empresas pueden integrar SMS en su estrategia de marketing para enviar campañas promocionales personalizadas.

Caso de uso:

• Enviar descuentos especiales, códigos de promoción o recordatorios de eventos a clientes.
• Ofrecer alertas sobre productos en oferta o restock de artículos populares.
• Personalización del contenido según las preferencias del cliente.

Los SMS tienen tasas de apertura muy altas, lo que los convierte en una herramienta eficaz para captar la atención del público.

---

5. Gestión de logística y transporte

Aplicación: Empresas de logística, envíos o transporte pueden utilizar SMS para mantener informados a sus clientes sobre el estado de sus pedidos o servicios.

Caso de uso:

• Notificaciones de envío y entrega de paquetes.
• Alertas sobre retrasos o cambios en el transporte público.
• Confirmaciones de reserva en servicios de taxi o ride-sharing.

Esto mejora la experiencia del cliente al ofrecer información en tiempo real y reducir la incertidumbre.

---

6. Servicios educativos

Aplicación: Escuelas, universidades y plataformas de educación en línea pueden implementar SMS para notificar a estudiantes y profesores sobre actividades importantes.

Caso de uso:

• Recordatorios de fechas de exámenes, inscripciones o eventos escolares.
• Envío de calificaciones o resultados.
• Alertas de emergencia, como cambios de horario o cierres.

El SMS asegura que los mensajes lleguen de forma rápida y directa, incluso en áreas con conectividad limitada.

---

La integración de envío de SMS con Java utilizando la API de 360nrs es una solución robusta y flexible para incorporar esta funcionalidad en tus aplicaciones.

Siguiendo este tutorial y ajustando los parámetros según tus necesidades, puedes enviar SMS de forma eficiente y gestionar las respuestas del servidor para realizar un seguimiento efectivo.

Implementar estas capacidades no solo mejora la comunicación con tus usuarios, sino que también aporta valor añadido a tus aplicaciones y sistemas. ¡Empieza a integrar SMS hoy mismo!