Como Receber Relatórios de Entrega SMPP através da API SMPP

O protocolo Short Message Peer-to-Peer (SMPP) é um pilar fundamental da comunicação moderna por SMS, permitindo que Entidades de Mensagens Curtas Externas (ESMEs) troquem mensagens e relatórios de entrega com Centros de Serviço de Mensagens Curtas (SMSCs). Para desenvolvedores que utilizam a API SMPP com o Ozeki SMS Gateway, entender como receber relatórios de entrega é essencial para rastrear o status das mensagens SMS enviadas. Este artigo fornece um guia abrangente sobre como receber relatórios de entrega SMPP no nível do protocolo, focando nas Unidades de Dados de Protocolo (PDUs) SMPP necessárias para configuração de conexão, manutenção e recebimento de relatórios de entrega, utilizando o Ozeki SMS Gateway como a principal plataforma de servidor de API SMPP.

Introdução aos Relatórios de Entrega SMPP e ao Ozeki SMS Gateway

Os relatórios de entrega SMPP são notificações enviadas pelo SMSC para informar a ESME sobre o status de um SMS previamente enviado, como se foi entregue, falhou ou foi rejeitado. Esses relatórios são essenciais para aplicações que exigem confirmação da entrega da mensagem, como notificações transacionais ou campanhas de marketing. O Ozeki SMS Gateway, um software SMPP robusto que suporta as versões 3.3, 3.4 e 5.0, simplifica o processo de manipulação de relatórios de entrega SMPP através de sua interface intuitiva e poderosas opções de configuração. Este artigo detalha as PDUs SMPP envolvidas na configuração de uma conexão de cliente de API SMPP, sua manutenção e recebimento de relatórios de entrega, com orientações práticas para usuários do Ozeki SMS Gateway.

Entendendo as PDUs SMPP para Relatórios de Entrega

O protocolo SMPP depende das Unidades de Dados de Protocolo (PDUs) para gerenciar a comunicação entre o cliente SMPP (por exemplo, Ozeki SMS Gateway) e o SMSC. Para receber relatórios de entrega, o cliente deve estabelecer uma conexão, mantê-la e processar os relatórios de entrega recebidos. As PDUs principais envolvidas são:

  • bind_transceiver: Estabelece uma conexão para envio e recebimento de SMS e relatórios de entrega.
  • enquire_link: Mantém a conexão para garantir a recepção contínua de relatórios de entrega.
  • deliver_sm: Entrega relatórios de entrega (e mensagens SMS) recebidos do SMSC para o cliente.
  • unbind: Encerra a sessão SMPP.

A seguir, exploramos cada PDU, sua estrutura e seu papel no recebimento de relatórios de entrega SMPP usando a API SMPP com o Ozeki SMS Gateway.

Configurando uma Conexão de Cliente SMPP API

Receber relatórios de entrega SMPP requer uma conexão estável de cliente SMPP API com o SMSC. O Ozeki SMS Gateway simplifica esse processo, mas entender as operações em nível de protocolo é essencial para usuários avançados e solução de problemas.

1. Configurando o Cliente SMPP no Ozeki SMS Gateway

Para configurar uma conexão de cliente SMPP API no Ozeki SMS Gateway para receber relatórios de entrega, siga estas etapas:

  1. Acesse o Console de Gerenciamento: Faça login na interface web do Ozeki SMS Gateway usando a conta de administrador (nome de usuário padrão: "admin").
  2. Crie uma Nova Conexão: No painel "Conexões", clique em "Adicionar nova conexão" e selecione "Cliente SMPP" na seção "Conexões SMS IP".
  3. Insira as Configurações SMPP: Forneça os seguintes detalhes, geralmente fornecidos pelo seu provedor de serviços SMS:
    • Nome do Host: O endereço IP ou nome do host do SMSC (por exemplo, "192.168.1.1").
    • Número da Porta: A porta TCP/IP para comunicação SMPP (o padrão é 9500, confirme com seu provedor).
    • Nome de Usuário (System ID): Seu identificador de conta SMSC (por exemplo, "smppuser").
    • Senha: A senha para o System ID (por exemplo, "password123").
    • Versão SMPP: Selecione v3.4 para suporte transceptor, que é ideal para envio e recebimento.
    • Tipo de Sistema: Opcional, geralmente "SMPP", conforme especificado pelo provedor.
    • Endereço do Remetente: O número de telefone padrão para SMS de saída (por exemplo, "+1234567890").
    • Faixa de Endereço: Opcional, usado para receber mensagens ou relatórios para números específicos.
  4. Modo de Vinculação: Selecione "Transceptor" para permitir o envio de SMS e o recebimento de relatórios de entrega em uma única conexão.
  5. Habilitar Relatórios de Entrega: Na aba "Avançado", marque "Solicitar relatório de entrega" para garantir que o SMSC envie relatórios de entrega para mensagens enviadas.
  6. Configurações de Keepalive: Habilite "Enviar pacotes keepalive" para manter a conexão para recebimento contínuo de relatórios.
  7. Habilitar Registro: Na aba "Avançado", habilite "Registrar Eventos de Comunicação" para capturar PDUs SMPP para depuração.
  8. Salvar e Conectar: Clique em "OK" para salvar, depois em "Conectar" para iniciar a conexão SMPP API.

Essas configurações preparam o Ozeki SMS Gateway para estabelecer uma conexão SMPP API usando o PDU bind_transceiver, permitindo o recebimento de relatórios de entrega.

2. O PDU bind_transceiver

O PDU bind_transceiver autentica o cliente SMPP com o SMSC e estabelece uma conexão para enviar SMS e receber relatórios de entrega. É o primeiro passo para habilitar a funcionalidade SMPP API.

Estrutura do PDU bind_transceiver

Comprimento do Comando: 4 bytes (comprimento total do PDU)
ID do Comando: 0x00000009 (bind_transceiver)
Status do Comando: 0x00000000 (definido como 0 para solicitações)
Número de Sequência: Identificador único para o PDU
System ID: Nome de usuário para autenticação (por exemplo, "smppuser")
Senha: Senha para autenticação (por exemplo, "password123")
Tipo de Sistema: Opcional, geralmente "SMPP"
Versão da Interface: Versão SMPP (por exemplo, 0x34 para v3.4)
Faixa de Endereço: Opcional, para receber mensagens ou relatórios

Exemplo de PDU bind_transceiver (hexadecimal):

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

Explicação:

  • Comprimento do Comando (0000002F): Comprimento total do PDU (47 bytes).
  • ID do Comando (00000009): Identifica o PDU como bind_transceiver.
  • Status do Comando (00000000): Definido como 0 para a solicitação.
  • Número de Sequência (00000001): Um ID único para rastrear o PDU.
  • System ID (736D70707573657200): ASCII para "smppuser" com um terminador nulo.
  • Senha (70617373776F726431323300): ASCII para "password123" com um terminador nulo.
  • Tipo de Sistema (534D505000): ASCII para "SMPP" com um terminador nulo.
  • Versão da Interface (34): Indica SMPP v3.4.
  • Faixa de Endereço (00): Nulo, pois é opcional.

O SMSC responde com um PDU bind_transceiver_resp. Um status de comando 0x00000000 indica uma conexão bem-sucedida. O Ozeki SMS Gateway registra essa interação no log "Eventos de Comunicação", que é útil para verificar a conexão.

Mantendo a Conexão SMPP API

Uma conexão estável é crucial para receber relatórios de entrega SMPP, pois interrupções podem resultar em atualizações de status perdidas. O PDU enquire_link é usado para manter a conexão ativa.

O PDU enquire_link

O PDU enquire_link é enviado periodicamente pelo cliente SMPP para confirmar o status da conexão, evitando desconexão por inatividade.

Estrutura do PDU enquire_link

Comprimento do Comando: 0x00000010 (16 bytes)
ID do Comando: 0x00000015 (enquire_link)
Status do Comando: 0x00000000 (definido como 0 para solicitações)
Número de Sequência: Identificador único para o PDU

Exemplo de PDU enquire_link (hexadecimal):

00000010 00000015 00000000 00000002

Explicação:

  • Comprimento do Comando (00000010): Comprimento total (16 bytes).
  • ID do Comando (00000015): Identifica o PDU como enquire_link.
  • Status do Comando (00000000): Definido como 0 para a solicitação.
  • Número de Sequência (00000002): Um ID único para rastrear o PDU.

O SMSC responde com um PDU enquire_link_resp para confirmar o status da conexão. No Ozeki SMS Gateway, habilitar "Enviar pacotes keepalive" na aba "Comunicação" garante que os PDUs enquire_link sejam enviados automaticamente (por exemplo, a cada 30 segundos). Isso é crítico para manter uma conexão SMPP API confiável para recebimento de relatórios de entrega.

Recebendo Relatórios de Entrega SMPP

Os relatórios de entrega SMPP são recebidos via o PDU deliver_sm, que o SMSC envia ao cliente para relatar o status de um SMS previamente enviado. O PDU contém detalhes como o ID da mensagem, status de entrega e timestamp.

O PDU deliver_sm para Relatórios de Entrega

O PDU deliver_sm é usado tanto para mensagens SMS recebidas quanto para relatórios de entrega. Para relatórios de entrega, o campo ESM Class do PDU é definido para indicar um recibo de entrega (normalmente 0x04), e o conteúdo da mensagem inclui um relatório estruturado com informações de status.

Estrutura do PDU deliver_sm (Relatório de Entrega)

Comprimento do Comando: Variável (depende do comprimento do relatório)
ID do Comando: 0x00000005 (deliver_sm)
Status do Comando: 0x00000000 (definido como 0 para solicitações)
Número de Sequência: Identificador único para o PDU
Tipo de Serviço: Opcional, frequentemente nulo
TON do Endereço de Origem: Tipo de Número para o remetente (SMSC ou destinatário)
NPI do Endereço de Origem: Indicador de Plano de Numeração para o remetente
Endereço de Origem: Número de telefone do remetente ou identificador do SMSC
TON do Endereço de Destino: Tipo de Número para o destinatário (ESME)
NPI do Endereço de Destino: Indicador de Plano de Numeração para o destinatário
Endereço de Destino: Número de telefone do destinatário (ex., número virtual do ESME)
Classe ESM: 0x04 (indica recibo de entrega)
Codificação de Dados: Codificação de caracteres (ex., 0x00 para GSM 7-bit)
Mensagem Curta: Texto do relatório de entrega (ex., "id:12345 sub:001 dlvrd:001 submit date:2505270415 done date:2505270416 stat:DELIVRD err:000")
Parâmetros Opcionais: Campos TLV como receipted_message_id e message_state

Exemplo de PDU deliver_sm (hexadecimal):

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

Explicação:

  • Comprimento do Comando (0000007A): Comprimento total (122 bytes).
  • ID do Comando (00000005): Identifica o PDU como deliver_sm.
  • Status do Comando (00000000): Definido como 0 para a solicitação.
  • Número de Sequência (00000003): Um ID único para rastrear o PDU.
  • Tipo de Serviço (00): Nulo, pois é opcional.
  • TON do Endereço de Origem (01): Número internacional.
  • NPI do Endereço de Origem (01): Plano de numeração ISDN/telefônico.
  • Endereço de Origem (2B3938373635343332313000): ASCII para "+9876543210" (número do destinatário).
  • TON do Endereço de Destino (01): Número internacional.
  • NPI do Endereço de Destino (01): Plano de numeração ISDN/telefônico.
  • Endereço de Destino (2B3132333435363738393000): ASCII para "+1234567890" (número do ESME).
  • Classe ESM (04): Indica um recibo de entrega.
  • Codificação de Dados (00): Codificação GSM 7-bit.
  • Mensagem Curta: ASCII para "id:12345 sub:001 dlvrd:001 submit date:2505270415 done date:2505270416 stat:DELIVRD err:000".

Campos do Relatório de Entrega:

  • id: ID da mensagem atribuído pelo SMSC (ex., "12345").
  • sub: Número de destinatários (ex., "001").
  • dlvrd: Número de mensagens entregues (ex., "001").
  • submit date: Timestamp de envio (ex., "2505270415" para 27 de maio de 2025, 04:15).
  • done date: Timestamp de entrega (ex., "2505270416").
  • stat: Status de entrega (ex., "DELIVRD" para entregue, "UNDELIV" para não entregue).
  • err: Código de erro (ex., "000" para nenhum erro).

O cliente deve responder com um PDU deliver_sm_resp para confirmar o recebimento. O Ozeki SMS Gateway lida com isso automaticamente e encaminha o relatório de entrega para o aplicativo ou banco de dados configurado, registrando-o no painel "Mensagens".

Configurando o Ozeki SMS Gateway para Recebimento de Relatórios de Entrega

Para garantir que o Ozeki SMS Gateway processe corretamente os relatórios de entrega SMPP:

  1. Habilitar Relatórios de Entrega: Na configuração do cliente SMPP, marque "Solicitar relatório de entrega" na aba "Avançado" para instruir o SMSC a enviar relatórios de entrega.
  2. Configuração de Número Virtual: Certifique-se de que o SMSC está configurado para enviar relatórios de entrega para o número virtual ou faixa de endereços especificada nas configurações do cliente SMPP.
  3. Integração com Banco de Dados: Configure o Ozeki para armazenar relatórios de entrega em um banco de dados modificando a instrução SQL SELECT na configuração do "Usuário de banco de dados" (ex., "SELECT id, sender, receiver, msg, msgtype, status FROM ozekimessagein WHERE msgtype='DLR'").
  4. Registro: Habilite o registro de PDUs SMPP para monitorar PDUs deliver_sm recebidos para depuração.

Com essas configurações, o Ozeki SMS Gateway processará e armazenará os relatórios de entrega, tornando-os acessíveis para aplicativos ou análises posteriores.

Encerrando a Conexão da API SMPP

Quando a sessão da API SMPP não for mais necessária, o cliente envia um PDU unbind para encerrar a conexão de forma adequada.

O PDU unbind

O PDU unbind sinaliza ao SMSC para encerrar a sessão SMPP.

Estrutura do PDU unbind

Comprimento do Comando: 0x00000010 (16 bytes)
ID do Comando: 0x00000006 (unbind)
Status do Comando: 0x00000000 (definido como 0 para solicitações)
Número de Sequência: Identificador único para o PDU

Exemplo de PDU unbind (hexadecimal):

00000010 00000006 00000000 00000004

Explicação:

  • Comprimento do Comando (00000010): Comprimento total (16 bytes).
  • ID do Comando (00000006): Identifica o PDU como unbind.
  • Status do Comando (00000000): Definido como 0 para a solicitação.
  • Número de Sequência (00000004): Um ID único para rastrear o PDU.

O SMSC responde com um PDU unbind_resp, confirmando o encerramento da sessão. No Ozeki SMS Gateway, isso pode ser iniciado clicando em "Desconectar" no painel "Conexões".

Melhores Práticas para o Tratamento de Relatórios de Entrega via API SMPP

Para otimizar sua implementação da API SMPP para receber relatórios de entrega com o Ozeki SMS Gateway:

  • Solicitar Relatórios de Entrega: Sempre ative a opção "Solicitar relatório de entrega" ao enviar SMS para garantir que o SMSC gere os relatórios.
  • Monitorar Logs: Use os logs de PDU SMPP para solucionar problemas com PDUs deliver_sm, especialmente para relatórios de entrega.
  • Usar Modo Transceptor: Prefira o modo transceptor para eficiência, pois ele suporta tanto o envio de SMS quanto o recebimento de relatórios de entrega.
  • Conexões Seguras: Use SMPPS (SMPP sobre SSL/TLS) se suportado pelo seu provedor para garantir a transmissão segura de relatórios de entrega.
  • Analisar Relatórios de Entrega: Configure aplicativos para analisar o campo Short Message da PDU deliver_sm e extrair informações de status (ex.: "DELIVRD" ou "UNDELIV") para insights acionáveis.
Conclusão

Receber relatórios de entrega SMPP usando a API SMPP com o Ozeki SMS Gateway envolve estabelecer uma conexão com a PDU bind_transceiver, mantê-la com PDUs enquire_link e processar relatórios de entrega via PDU deliver_sm. Ao configurar o Ozeki SMS Gateway corretamente e entender o protocolo SMPP subjacente, os desenvolvedores podem construir sistemas confiáveis para rastrear o status de entrega de SMS. A robustez da API SMPP e a configuração flexível do Ozeki a tornam uma excelente escolha para gerenciar relatórios de entrega em aplicações de SMS de alto volume. Para mais detalhes, consulte a documentação do Ozeki SMS Gateway ou entre em contato com seu provedor de SMS para requisitos de configuração específicos.

More information