Cómo recibir informes de entrega SMPP a través de la API SMPP

El protocolo Short Message Peer-to-Peer (SMPP) es un pilar fundamental de la comunicación moderna por SMS, permitiendo que las Entidades Externas de Mensajes Cortos (ESMEs) intercambien mensajes e informes de entrega con los Centros de Servicio de Mensajes Cortos (SMSCs). Para los desarrolladores que utilizan la API SMPP con Ozeki SMS Gateway, entender cómo recibir informes de entrega es crucial para rastrear el estado de los mensajes SMS enviados. Este artículo proporciona una guía completa sobre cómo recibir informes de entrega SMPP a nivel de protocolo, centrándose en las Unidades de Datos de Protocolo (PDUs) necesarias para la configuración de la conexión, su mantenimiento y la recepción de informes de entrega, utilizando Ozeki SMS Gateway como plataforma principal de servidor API SMPP.

Introducción a los informes de entrega SMPP y Ozeki SMS Gateway

Los informes de entrega SMPP son notificaciones enviadas por el SMSC para informar a la ESME sobre el estado de un SMS previamente enviado, como si fue entregado, falló o fue rechazado. Estos informes son esenciales para aplicaciones que requieren confirmación de entrega de mensajes, como notificaciones transaccionales o campañas de marketing. Ozeki SMS Gateway, un software SMPP robusto que soporta las versiones 3.3, 3.4 y 5.0, simplifica el proceso de manejo de informes de entrega SMPP a través de su interfaz intuitiva y potentes opciones de configuración. Este artículo detalla las PDUs SMPP involucradas en la configuración de una conexión cliente API SMPP, su mantenimiento y la recepción de informes de entrega, con orientación práctica para usuarios de Ozeki SMS Gateway.

Entendiendo las PDUs SMPP para informes de entrega

El protocolo SMPP depende de las Unidades de Datos de Protocolo (PDUs) para gestionar la comunicación entre el cliente SMPP (por ejemplo, Ozeki SMS Gateway) y el SMSC. Para recibir informes de entrega, el cliente debe establecer una conexión, mantenerla y procesar los informes de entrega entrantes. Las PDUs clave involucradas son:

• bind_transceiver: Establece una conexión para enviar y recibir SMS e informes de entrega.
• enquire_link: Mantiene la conexión para asegurar la recepción continua de informes de entrega.
• deliver_sm: Entrega informes de entrega (y mensajes SMS) entrantes desde el SMSC al cliente.
• unbind: Termina la sesión SMPP.

A continuación, exploramos cada PDU, su estructura y su papel en la recepción de informes de entrega SMPP utilizando la API SMPP con Ozeki SMS Gateway.

Configuración de una conexión cliente API SMPP

Recibir informes de entrega SMPP requiere una conexión estable del cliente API SMPP al SMSC. Ozeki SMS Gateway simplifica este proceso, pero entender las operaciones a nivel de protocolo es esencial para usuarios avanzados y solución de problemas.

1. Configuración del cliente SMPP en Ozeki SMS Gateway

Para configurar una conexión cliente API SMPP en Ozeki SMS Gateway para recibir informes de entrega, sigue estos pasos:

1. Accede a la Consola de Gestión: Inicia sesión en la interfaz web de Ozeki SMS Gateway utilizando la cuenta de administrador (nombre de usuario predeterminado: "admin").
2. Crea una Nueva Conexión: En el panel "Conexiones", haz clic en "Añadir nueva conexión" y selecciona "Cliente SMPP" en la sección "Conexiones SMS IP".
3. Ingresa los Ajustes SMPP: Proporciona los siguientes detalles, generalmente suministrados por tu proveedor de servicios SMS:
   • Nombre del Host: La dirección IP o nombre de host del SMSC (por ejemplo, "192.168.1.1").
   • Número de Puerto: El puerto TCP/IP para la comunicación SMPP (el predeterminado es 9500, confirma con tu proveedor).
   • Nombre de Usuario (ID del Sistema): Tu identificador de cuenta SMSC (por ejemplo, "smppuser").
   • Contraseña: La contraseña para el ID del Sistema (por ejemplo, "password123").
   • Versión SMPP: Selecciona v3.4 para soporte de transceptor, que es óptimo para enviar y recibir.
   • Tipo de Sistema: Opcional, a menudo "SMPP", como lo especifica el proveedor.
   • Dirección del Remitente: El número de teléfono predeterminado para SMS salientes (por ejemplo, "+1234567890").
   • Rango de Direcciones: Opcional, utilizado para recibir mensajes o informes para números específicos.
4. Modo de Enlace: Selecciona "Transceptor" para habilitar tanto el envío de SMS como la recepción de informes de entrega sobre una sola conexión.
5. Habilita Informes de Entrega: En la pestaña "Avanzado", marca "Solicitar informe de entrega" para asegurar que el SMSC envíe informes de entrega para los mensajes enviados.
6. Ajustes de Keepalive: Habilita "Enviar paquetes keepalive" para mantener la conexión y la recepción continua de informes.
7. Habilita Registro: En la pestaña "Avanzado", habilita "Registrar Eventos de Comunicación" para capturar las PDUs SMPP para depuración.
8. Guarda y Conecta: Haz clic en "OK" para guardar, luego en "Conectar" para iniciar la conexión API SMPP.

Estos ajustes preparan Ozeki SMS Gateway para establecer una conexión API SMPP utilizando la PDU bind_transceiver, permitiendo la recepción de informes de entrega.

2. La PDU bind_transceiver

La PDU bind_transceiver autentica el cliente SMPP con el SMSC y establece una conexión tanto para enviar SMS como para recibir informes de entrega. Es el primer paso para habilitar la funcionalidad API SMPP.

Estructura de la PDU bind_transceiver

Longitud del Comando: 4 bytes (longitud total de la PDU)
ID del Comando: 0x00000009 (bind_transceiver)
Estado del Comando: 0x00000000 (establecido en 0 para solicitudes)
Número de Secuencia: Identificador único para la PDU
ID del Sistema: Nombre de usuario para autenticación (por ejemplo, "smppuser")
Contraseña: Contraseña para autenticación (por ejemplo, "password123")
Tipo de Sistema: Opcional, a menudo "SMPP"
Versión de la Interfaz: Versión SMPP (por ejemplo, 0x34 para v3.4)
Rango de Direcciones: Opcional, para recibir mensajes o informes

Ejemplo de PDU bind_transceiver (hexadecimal):

0000002F 00000009 00000000 00000001 736D70707573657200 70617373776F726431323300 534D505000 34 00

Explicación:

• Longitud del Comando (0000002F): Longitud total de la PDU (47 bytes).
• ID del Comando (00000009): Identifica la PDU como bind_transceiver.
• Estado del Comando (00000000): Establecido en 0 para la solicitud.
• Número de Secuencia (00000001): Un ID único para rastrear la PDU.
• ID del Sistema (736D70707573657200): ASCII para "smppuser" con un terminador nulo.
• Contraseña (70617373776F726431323300): ASCII para "password123" con un terminador nulo.
• Tipo de Sistema (534D505000): ASCII para "SMPP" con un terminador nulo.
• Versión de la Interfaz (34): Indica SMPP v3.4.
• Rango de Direcciones (00): Nulo, ya que es opcional.

El SMSC responde con una PDU bind_transceiver_resp. Un estado de comando de 0x00000000 indica una conexión exitosa. Ozeki SMS Gateway registra esta interacción en el registro "Eventos de Comunicación", lo que es útil para verificar la conexión.

Mantenimiento de la conexión API SMPP

Una conexión estable es crucial para recibir informes de entrega SMPP, ya que las interrupciones pueden resultar en actualizaciones de estado perdidas. La PDU enquire_link se utiliza para mantener la conexión activa.

La PDU enquire_link

La PDU enquire_link se envía periódicamente por el cliente SMPP para confirmar el estado de la conexión, evitando la desconexión por inactividad.

Estructura de la PDU enquire_link

Longitud del Comando: 0x00000010 (16 bytes)
ID del Comando: 0x00000015 (enquire_link)
Estado del Comando: 0x00000000 (establecido en 0 para solicitudes)
Número de Secuencia: Identificador único para la PDU

Ejemplo de PDU enquire_link (hexadecimal):

00000010 00000015 00000000 00000002

Explicación:

• Longitud del Comando (00000010): Longitud total (16 bytes).
• ID del Comando (00000015): Identifica la PDU como enquire_link.
• Estado del Comando (00000000): Establecido en 0 para la solicitud.
• Número de Secuencia (00000002): Un ID único para rastrear la PDU.

El SMSC responde con una PDU enquire_link_resp para confirmar el estado de la conexión. En Ozeki SMS Gateway, habilitar "Enviar paquetes keepalive" en la pestaña "Comunicación" asegura que las PDUs enquire_link se envíen automáticamente (por ejemplo, cada 30 segundos). Esto es crítico para mantener una conexión API SMPP confiable para la recepción de informes de entrega.

Recepción de informes de entrega SMPP

Los informes de entrega SMPP se reciben a través de la PDU deliver_sm, que el SMSC envía al cliente para informar el estado de un SMS previamente enviado. La PDU contiene detalles como el ID del mensaje, el estado de entrega y la marca de tiempo.

La PDU deliver_sm para informes de entrega

La PDU deliver_sm se utiliza tanto para mensajes SMS entrantes como para informes de entrega. Para informes de entrega, el campo ESM Class de la PDU se establece para indicar un recibo de entrega (típicamente 0x04), y el contenido del mensaje incluye un informe estructurado con información de estado.

Estructura de la PDU deliver_sm (Informe de Entrega)

Longitud del Comando: Variable (depende de la longitud del informe)
ID del Comando: 0x00000005 (deliver_sm)
Estado del Comando: 0x00000000 (establecido en 0 para solicitudes)
Número de Secuencia: Identificador único para la PDU
Tipo de Servicio: Opcional, a menudo nulo
TON de Dirección de Origen: Tipo de Número para el remitente (SMSC o destinatario)
NPI de Dirección de Origen: Indicador de Plan de Numeración para el remitente
Dirección de Origen: Número de teléfono del remitente o identificador del SMSC
TON de Dirección de Destino: Tipo de Número para el destinatario (ESME)
NPI de Dirección de Destino: Indicador de Plan de Numeración para el destinatario
Dirección de Destino: Número de teléfono del destinatario (por ejemplo, número virtual de la ESME)
ESM Class: 0x04 (indica recibo de entrega)
Codificación de Datos: Codificación de caracteres (por ejemplo, 0x00 para GSM 7-bit)
Mensaje Corto: Texto del informe de entrega (por ejemplo, "id:12345 sub:001 dlvrd:001 submit date:2505270415 done date:2505270416 stat:DELIVRD err:000")
Parámetros Opcionales: Campos TLV como receipted_message_id y message_state

Ejemplo de PDU deliver_sm (hexadecimal):

0000007A 00000005 00000000 00000003 00 01 01 2B3938373635343332313000 01 01 2B3132333435363738393000 04 00 00 00 00 69643A3132333435207375623A30303120646C7672643A303031207375626D697420646174653A3235303532373034313520646F6E6520646174653A3235303532373034313620737461743A44454C49565244206572723A303030

Explicación:

• Longitud del Comando (0000007A): Longitud total (122 bytes).
• ID del Comando (00000005): Identifica la PDU como deliver_sm.
• Estado del Comando (00000000): Establecido en 0 para la solicitud.
• Número de Secuencia (00000003): Un ID único para rastrear la PDU.
• Tipo de Servicio (00): Nulo, ya que es opcional.
• TON de Dirección de Origen (01): Número internacional.
• NPI de Dirección de Origen (01): Plan de numeración ISDN/teléfono.
• Dirección de Origen (2B3938373635343332313000): ASCII para "+9876543210" (número del destinatario).
• TON de Dirección de Destino (01): Número internacional.
• NPI de Dirección de Destino (01): Plan de numeración ISDN/teléfono.
• Dirección de Destino (2B3132333435363738393000): ASCII para "+1234567890" (número de la ESME).
• ESM Class (04): Indica un recibo de entrega.
• Codificación de Datos (00): Codificación GSM 7-bit.
• Mensaje Corto: ASCII para "id:12345 sub:001 dlvrd:001 submit date:2505270415 done date:2505270416 stat:DELIVRD err:000".

Campos del Informe de Entrega:

• id: ID del mensaje asignado por el SMSC (por ejemplo, "12345").
• sub: Número de destinatarios (por ejemplo, "001").
• dlvrd: Número de mensajes entregados (por ejemplo, "001").
• submit date: Marca de tiempo de envío (por ejemplo, "2505270415" para 27 de mayo de 2025, 04:15).
• done date: Marca de tiempo de entrega (por ejemplo, "2505270416").
• stat: Estado de entrega (por ejemplo, "DELIVRD" para entregado, "UNDELIV" para no entregable).
• err: Código de error (por ejemplo, "000" para sin error).

El cliente debe responder con una PDU deliver_sm_resp para confirmar la recepción. Ozeki SMS Gateway maneja esto automáticamente y dirige el informe de entrega a la aplicación o base de datos configurada, registrándolo en el panel "Mensajes".

Configuración de Ozeki SMS Gateway para la recepción de informes de entrega

Para asegurar que Ozeki SMS Gateway procese correctamente los informes de entrega SMPP:

1. Habilita Informes de Entrega: En la configuración del cliente SMPP, marca "Solicitar informe de entrega" en la pestaña "Avanzado" para instruir al SMSC a enviar informes de entrega.
2. Configuración de Número Virtual: Asegúrate de que el SMSC esté configurado para enviar informes de entrega al número virtual o rango de direcciones especificado en los ajustes del cliente SMPP.
3. Integración con Base de Datos: Configura Ozeki para almacenar informes de entrega en una base de datos modificando la sentencia SQL SELECT en la configuración del "Usuario de Base de Datos" (por ejemplo, "SELECT id, sender, receiver, msg, msgtype, status FROM ozekimessagein WHERE msgtype='DLR'").
4. Registro: Habilita el registro de PDUs SMPP para monitorear las PDUs deliver_sm entrantes para depuración.

Con estos ajustes, Ozeki SMS Gateway procesará y almacenará los informes de entrega, haciéndolos accesibles para aplicaciones o análisis posteriores.

Terminación de la conexión API SMPP

Cuando la sesión API SMPP ya no sea necesaria, el cliente envía una PDU unbind para terminar la conexión de manera ordenada.

La PDU unbind

La PDU unbind señala al SMSC que cierre la sesión SMPP.

Estructura de la PDU unbind

Longitud del Comando: 0x00000010 (16 bytes)
ID del Comando: 0x00000006 (unbind)
Estado del Comando: 0x00000000 (establecido en 0 para solicitudes)
Número de Secuencia: Identificador único para la PDU

Ejemplo de PDU unbind (hexadecimal):

00000010 00000006 00000000 00000004

Explicación:

• Longitud del Comando (00000010): Longitud total (16 bytes).
• ID del Comando (00000006): Identifica la PDU como unbind.
• Estado del Comando (00000000): Establecido en 0 para la solicitud.
• Número de Secuencia (00000004): Un ID único para rastrear la PDU.

El SMSC responde con una PDU unbind_resp, confirmando la terminación de la sesión. En Ozeki SMS Gateway, esto puede iniciarse haciendo clic en "Desconectar" en el panel "Conexiones".

Mejores prácticas para el manejo de informes de entrega API SMPP

Para optimizar tu implementación API SMPP para recibir informes de entrega con Ozeki SMS Gateway:

• Solicita Informes de Entrega: Siempre habilita la opción "Solicitar informe de entrega" al enviar SMS para asegurar que el SMSC genere informes.
• Monitorea los Registros: Utiliza los registros de PDUs SMPP para solucionar problemas con las PDUs deliver_sm, especialmente para informes de entrega.
• Usa Modo Transceptor: Prefiere el modo transceptor para eficiencia, ya que soporta tanto el envío de SMS como la recepción de informes de entrega.
• Conexiones Seguras: Usa SMPPS (SMPP sobre SSL/TLS) si tu proveedor lo soporta para asegurar la transmisión segura de informes de entrega.
• Analiza Informes de Entrega: Configura aplicaciones para analizar el campo "Mensaje Corto" de la PDU deliver_sm para extraer información de estado (por ejemplo, "DELIVRD" o "UNDELIV") para insights accionables.

Conclusión

Recibir informes de entrega SMPP utilizando la API SMPP con Ozeki SMS Gateway implica establecer una conexión con la PDU bind_transceiver, mantenerla con PDUs enquire_link y procesar informes de entrega a través de la PDU deliver_sm. Al configurar Ozeki SMS Gateway correctamente y entender el protocolo SMPP subyacente, los desarrolladores pueden construir sistemas confiables para rastrear el estado de entrega de SMS. La robustez de la API SMPP y la configuración flexible de Ozeki lo convierten en una excelente opción para gestionar informes de entrega en aplicaciones de SMS de alto volumen. Para más detalles, consulta la documentación de Ozeki SMS Gateway o contacta a tu proveedor de servicios SMS para requisitos de configuración específicos.