API de SMS vs SMPP: qual conexão usar?

Este guia é para engenheiros e líderes técnicos que estão decidindo como se conectar a um fornecedor de SMS: por uma API HTTP/REST de SMS, por SMPP ou pelas duas. Ele explica como as duas opções realmente diferem no protocolo e na operação, para que você escolha a interface certa para cada tipo de tráfego e planeje uma migração caso a primeira escolha deixe de atender.

Para uma visão mais ampla de padrões de integração, incluindo webhooks e idempotência, veja nosso guia de integração de API de mensagens.

Qual é a diferença entre uma API de SMS e o SMPP?

Uma API REST de SMS envia cada mensagem como uma requisição HTTPS separada e devolve um ID de mensagem. O SMPP (Short Message Peer-to-Peer) mantém aberta uma única sessão autenticada e duradoura, e troca por ela mensagens binárias, chamadas PDUs, nos dois sentidos. A REST prioriza a simplicidade; o SMPP prioriza volume constante de SMS.

Como funciona uma API REST de SMS?

Você faz um POST HTTPS com um token e um corpo JSON, e o fornecedor responde com um ID. Cada requisição é independente, então dá para enviar de qualquer servidor, função ou contêiner sem gerenciar conexões.

Um envio típico com a nossa API fica assim:

curl -X POST https://api.broadnet.me/sms/sendSms \
  -H "Authorization: Bearer $BROADNET_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "senderId": "OmniDemo",
    "destinationNumber": "971500000000",
    "message": "Your OmniDemo code is 482913",
    "messageType": "TEXT"
  }'

A resposta é 200 OK com o ID da mensagem em texto simples. O status final chega depois ao seu webhook como SUBMITTED, SENT, DELIVERED, FAILED ou REJECTED. Nomes de campos e opções estão na referência da API de SMS.

Pontos fortes da REST:

• Ferramentas conhecidas: qualquer linguagem, qualquer cliente HTTP, códigos de status padrão definidos na RFC 9110.
• Segurança simples: TLS em tudo e um token no cabeçalho Authorization.
• Envio em massa sem conexões: envie um arquivo de destinatários em uma única requisição, sem abrir sessão.
• Uma API para vários canais: o mesmo padrão envia modelos de WhatsApp ou cards de RCS.

Limites da REST: cada mensagem, ou cada lote, custa uma ida e volta HTTP, e você vai esbarrar em um limite de requisições por segundo antes de qualquer limite da operadora. Para a maior parte do tráfego de aplicações, isso nunca faz diferença.

Como funciona o SMPP?

O SMPP é um protocolo binário definido pela especificação SMPP v3.4, publicada pelo SMPP Developers Forum (depois SMS Forum) e ainda a versão mais usada. Seu sistema, chamado ESME (External Short Message Entity), conecta-se ao SMSC (Short Message Service Centre) do fornecedor e abre uma sessão chamada bind.

Tipos de bind

• Transmitter (TX), com bind_transmitter: apenas envia mensagens.
• Receiver (RX), com bind_receiver: apenas recebe relatórios de entrega e mensagens de entrada.
• Transceiver (TRX), com bind_transceiver: as duas coisas na mesma sessão. É a escolha mais comum.

Ciclo de vida da sessão

1. Abra uma conexão TLS com o host e a porta informados pelo fornecedor.
2. Envie bind_transceiver com seu system_id e senha, e aguarde uma resposta com command_status 0.
3. Envie mensagens com submit_sm. Cada submit_sm_resp devolve um message_id.
4. Receba os relatórios de entrega como deliver_sm e responda cada um com deliver_sm_resp.
5. Envie enquire_link periodicamente quando estiver ocioso, para que os dois lados saibam que a sessão continua ativa.
6. Encerre com unbind e aguarde o unbind_resp.

Cada PDU leva um número de sequência, e as respostas trazem o mesmo número; é assim que você associa um submit_sm_resp à mensagem enviada. Nossa documentação de SMPP cobre cada etapa com as nossas configurações.

O que é a janela do SMPP e por que ela importa?

Janela (windowing) significa enviar várias PDUs submit_sm antes de as respostas voltarem. O número de PDUs não confirmadas permitidas em trânsito é o tamanho da janela. É o principal motivo pelo qual o SMPP sustenta um throughput maior do que HTTP com uma requisição por vez.

Com janela 1, seu cliente envia uma mensagem, espera uma ida e volta completa pela resposta e só então envia a próxima. O throughput fica limitado pela latência da rede, não pela taxa acordada. Com uma janela maior, a conexão continua ocupada enquanto as respostas chegam.

Regras práticas:

• Use o tamanho de janela acordado com o fornecedor e nunca o ultrapasse; PDUs excedentes podem ser rejeitadas.
• Respeite a taxa acordada por bind. Se receber ESME_RTHROTTLED, reduza o ritmo e tente de novo com backoff.
• Acompanhe os números de sequência pendentes para que uma desconexão não faça você perder a referência de quais mensagens foram aceitas.
• Escale com mais binds, até o número acordado para a sua conta, e não com uma janela cada vez maior.

Os limites padrão da nossa API REST e dos binds SMPP estão em erros e limites; os limites da sua conta são confirmados quando o acesso é provisionado.

Como os relatórios de entrega diferem?

Na REST, o fornecedor envia um evento JSON ao seu webhook. No SMPP, o relatório de entrega chega como uma PDU deliver_sm na sessão, com o bit de relatório de entrega ativado em esm_class. Os dois são assíncronos; nem 200 OK nem submit_sm_resp significam que o aparelho recebeu a mensagem.

A especificação SMPP v3.4 traz o formato do texto do relatório de entrega como exemplo e deixa o formato exato a cargo do fabricante do SMSC, mas a maioria dos fornecedores o segue:

id:2603121407537573731 sub:001 dlvrd:001 submit date:2610100914 done date:2610100915 stat:DELIVRD err:000 text:Your OmniDemo code

Se os seus sistemas consomem as duas interfaces, mapeie os estados do SMPP para um único modelo de status. Um mapeamento típico:

Duas diferenças práticas importam mais do que o formato:

• Confirmação. Um cliente SMPP precisa responder a cada deliver_sm. Relatórios de entrega não confirmados são reenviados e podem deixar o bind lento. Um handler de webhook precisa responder 2xx rapidamente pelo mesmo motivo.
• Recuperação. Se o seu cliente SMPP cair, os relatórios de entrega esperam o próximo bind ou podem expirar na fila do fornecedor. Na REST, o fornecedor pode oferecer o reenvio de relatórios de entrega de um intervalo de datas. Pergunte como cada um funciona.

Saiba mais sobre o significado de cada status em status de entrega de mensagens explicados.

Como a codificação é tratada?

As duas interfaces precisam escolher entre GSM-7 e Unicode, e as duas dividem mensagens longas em segmentos. A diferença está em quem faz o trabalho.

• REST: você define um campo como messageType como TEXT ou UNICODE, e a plataforma segmenta as mensagens longas. Nossa API também tem POST /sms/identify para contar caracteres e segmentos antes do envio.
• SMPP: você define data_coding (0 para o alfabeto padrão GSM-7, 8 para UCS-2) e codifica os bytes por conta própria. Em mensagens longas, você adiciona um User Data Header a cada parte e define esm_class como 0x40, ou envia o texto inteiro no campo message_payload, se o fornecedor habilitar.

Pela 3GPP TS 23.040, um único SMS carrega 140 octetos: 160 caracteres GSM-7 ou 70 caracteres UCS-2, caindo para 153 ou 67 por parte quando o cabeçalho é adicionado. Uma única letra árabe, um emoji ou certos caracteres acentuados fora do alfabeto GSM-7 tornam a mensagem inteira Unicode. Bugs de codificação são a falha mais comum em integrações SMPP, então teste com acentos, árabe, emoji e textos longos. Veja nosso guia de limites de caracteres.

Como os modelos de segurança se comparam?

A REST depende de TLS e de um token Bearer por requisição. O SMPP v3.4 não tem criptografia própria e envia as credenciais no bind, então depende do transporte e dos controles de rede ao redor.

Para SMPP:

• Use TLS (o TLS 1.3 é definido na RFC 8446) ou um link privado; nunca SMPP sem criptografia pela internet pública.
• Cadastre os IPs de origem para que só os seus servidores consigam fazer bind.
• Guarde system_id e senha como segredos, separados por ambiente, e troque-os se forem expostos.
• Monitore falhas de bind, que podem indicar configuração errada ou uso indevido de credenciais.

Para REST:

• Mantenha o token apenas nos servidores, nunca em apps móveis ou em código do navegador.
• Evite interfaces HTTP legadas que passam usuário e senha na URL, onde acabam parando em logs.
• Proteja o webhook com HTTPS, um caminho difícil de adivinhar e validação rigorosa do corpo.

Quanto custa operar cada opção?

A REST quase não adiciona carga operacional: as requisições ou dão certo ou devolvem um erro que você pode tentar de novo. O SMPP adiciona um componente de longa duração que precisa ser monitorado e mantido.

Um cliente SMPP precisa de:

1. gerenciamento de conexão, com reconexão usando backoff e jitter em vez de um loop apertado;
2. keep-alives e detecção de conexões semiabertas silenciosas;
3. controle de janela e de taxa por bind;
4. rastreamento de sequência e reconciliação após desconexões;
5. confirmação e armazenamento de relatórios de entrega;
6. lógica de codificação e concatenação;
7. monitoramento do estado do bind, throughput, erros de throttling e atraso dos relatórios de entrega.

Bibliotecas open source maduras cuidam do protocolo, mas o comportamento ao redor delas continua sendo responsabilidade do seu time, inclusive durante uma janela de manutenção do fornecedor às 3 da manhã.

Quando usar cada uma?

Use REST, a menos que tenha um motivo claro para adicionar SMPP.

Escolha uma API REST de SMS quando

• você envia OTPs, alertas, notificações ou campanhas a partir de aplicações;
• precisa de WhatsApp, RCS ou outros canais além do SMS;
• sua plataforma roda em funções serverless ou contêineres de vida curta;
• seu time não tem experiência com SMPP nem necessidade de desenvolvê-la.

Escolha SMPP quando

• você envia um volume alto e constante de SMS e já atingiu os limites da REST;
• já opera um gateway SMPP ou uma plataforma de mensagens;
• é um agregador, operadora ou revendedor que conecta o tráfego de SMS dos seus próprios clientes;
• precisa do mesmo protocolo em vários fornecedores upstream.

Como é uma configuração híbrida?

Muitas empresas usam as duas na mesma conta: REST para o tráfego multicanal e de aplicações, SMPP para SMS em massa. A armadilha é acabar com dois modelos de entrega.

• Roteie por caso de uso, não de forma aleatória: por exemplo, OTP e WhatsApp pela REST, extratos por SMS em massa pelo SMPP.
• Normalize os status vindos de webhooks e de deliver_sm em uma única tabela indexada pelo ID da mensagem.
• Adote uma única política de ID de remetente (Sender ID) nas duas, já que os cadastros valem seja qual for a interface usada.
• Gere relatórios unificados, para que uma campanha dividida entre as duas interfaces mostre um único resultado.

Como migrar de uma API de SMS para SMPP?

Avance aos poucos, com as duas interfaces funcionando, e meça antes de transferir volume.

1. Confirme a necessidade: documente o volume ou o throughput que a REST não atende.
2. Solicite o provisionamento: informe países de destino, IDs de remetente, throughput de pico esperado e IPs de origem.
3. Escolha uma biblioteca cliente madura na sua stack e encapsule-a na sua própria interface de envio.
4. Construa primeiro o tratamento de relatórios de entrega, mapeado para o mesmo modelo de status dos seus webhooks.
5. Teste a codificação: GSM-7, acentos, árabe, emoji e mensagens de várias partes em aparelhos reais.
6. Teste falhas: derrube a conexão no meio do envio, provoque throttling e verifique a reconciliação.
7. Rode em paralelo: leve uma pequena parte de um tipo de tráfego para o SMPP e compare entrega e relatórios de entrega.
8. Transfira o volume em etapas, mantendo a REST como caminho de contingência.

Uma configuração de bind ilustrativa fica assim. Host, porta e limites são placeholders; os valores reais vêm com as credenciais provisionadas.

host:                 <provided with your bind>
port:                 <TLS port provided with your bind>
bind type:            transceiver
system_id:            <your system_id>
password:             <your password>
system_type:          (empty unless told otherwise)
interface_version:    0x34
source_addr_ton/npi:  5 / 0   (sender ID alfanumérico)
dest_addr_ton/npi:    1 / 1   (número internacional)
registered_delivery:  1       (solicitar recibos de entrega)
data_coding:          0 (GSM-7) or 8 (UCS-2)
enquire_link:         every 30 seconds while idle
window:               as agreed for your account

Exemplo prático: um varejista regional adiciona SMPP para extratos

A "Souq Rafiq" (fictícia), varejista online nos Emirados Árabes Unidos, no Egito e na Jordânia, envia OTPs e atualizações de pedido por uma API REST e modelos de WhatsApp pela mesma API. Os extratos mensais de conta, enviados por SMS para toda a base de clientes, cresceram a ponto de o job via REST demorar mais do que a empresa aceita.

• Decisão: manter OTP, atualizações de pedido e WhatsApp na REST. Levar os SMS de extrato mensal para um bind SMPP transceiver.
• Provisionamento: o time cadastra dois IPs de origem, confirma os IDs de remetente por país e acorda o throughput e o número de binds.
• Desenvolvimento: um pequeno serviço SMPP usa uma biblioteca open source, grava os relatórios de entrega na mesma tabela de status usada pelo webhook e expõe a mesma interface interna de envio do caminho REST.
• Testes: os extratos em árabe são confirmados como UCS-2, com concatenação correta em vários aparelhos.
• Rollout: um país migra primeiro. Depois de comparar a entrega e o tempo dos relatórios de entrega com a linha de base da REST, os outros países seguem, com a REST mantida como contingência.

Erros comuns

• Escolher SMPP por status. Se a REST atende ao seu volume, o SMPP só acrescenta trabalho.
• Rodar com janela 1 e depois culpar o fornecedor pelo throughput baixo.
• Não confirmar deliver_sm, o que provoca reenvio de relatórios de entrega e throttling.
• Reconectar em loop apertado após uma desconexão, o que pode parecer um ataque.
• Misturar short_message e message_payload na mesma PDU, causando erros de tamanho.
• SMPP sem criptografia pela internet, expondo credenciais e conteúdo.
• Dois modelos de status em uma configuração híbrida, gerando relatórios divergentes.
• Limites: este guia descreve práticas comuns. Tamanhos de janela, taxas, portas TLS e detalhes dos relatórios de entrega variam por fornecedor e por conta; confirme-os durante o provisionamento.

Como a OmniChannels.ai ajuda

A OmniChannels.ai oferece as duas opções. A API REST em https://api.broadnet.me usa um token Bearer e cobre SMS junto com WhatsApp, RCS, Messenger, Instagram, Telegram, Email e Push, com os status de entrega enviados ao seu webhook em um único formato. Para SMS de alto volume, binds SMPP 3.4 sobre TLS são provisionados por conta, com IPs de origem em allow-list, e usam as mesmas rotas de SMS pela conectividade direta da BroadNet com as operadoras. Revendedores e parceiros de atacado podem ter binds dedicados. Comece pela documentação de SMPP ou pelo quickstart, ou veja a visão geral para desenvolvedores.