Contas SMPP para clientes: binds, TPS, DLRs e faturamento

No momento em que um cliente técnico pergunta “posso fazer bind por SMPP?”, a sua plataforma deixa de ser um painel web e passa a ser, aos olhos dele, uma operadora. As contas SMPP para clientes são o recurso que conquista bancos, fornecedores de OTP, outros agregadores e qualquer desenvolvedor que já tenha uma biblioteca cliente SMPP, e também são o ponto em que uma configuração descuidada causa mais prejuízo: um cliente sem limite de vazão, um bind receiver que ninguém configurou, confirmações que não chegam a lugar nenhum, um livro-razão que o bind contorna. Este guia é a lista de verificação para fazer isso corretamente, desde o bind que você emite até o teste que você executa antes de liberar o cliente para a produção.

O que são, de fato, as contas SMPP para clientes

Pela API HTTP, um cliente envia uma requisição por mensagem e recebe uma resposta. Pelo SMPP, o cliente abre uma sessão TCP de longa duração com o seu servidor SMPP, autentica-se uma única vez com um system_id e uma senha e transmite as mensagens por essa sessão como pacotes binários chamados PDUs. A sua plataforma precisa executar um servidor SMPP (o do Smppcube escuta na porta 2775 e aparece no diagrama da página da plataforma), aceitar o bind, validar cada submit_sm em relação à conta do cliente, colocá-lo no mesmo fluxo de processamento alimentado pela API HTTP e, mais tarde, devolver a confirmação de entrega pela sessão como um deliver_sm.

Portanto, uma conta SMPP não é um produto separado, com faturamento próprio. É uma credencial em uma conta de cliente existente, somada a um conjunto de limites: quais modos de bind, a partir de quais IPs, quantas sessões, com que velocidade. A credencial é a parte pequena. Os limites são a conta.

Tipos de bind e o que permitir

O SMPP define três modos de bind, e a configuração da conta deve indicar quais o cliente pode usar:

• Transmitter: somente envio. O cliente submete mensagens e recebe as respostas de submit (o ID da mensagem), mas nada além disso. É simples, e é o motivo pelo qual as confirmações se perdem, porque um transmitter não tem canal para um deliver_sm.
• Receiver: somente recepção. O cliente recebe as confirmações de entrega e as mensagens recebidas (respostas originadas no celular, se você encaminhar alguma para ele) e não pode enviar.
• Transceiver: os dois em uma única sessão. É o que a maioria das bibliotecas cliente modernas abre por padrão e o que você deve recomendar, porque uma única sessão transporta os envios e as confirmações juntos, e não há nada que possa ficar desencontrado.

O padrão tradicional de um bind transmitter mais um bind receiver ainda existe, normalmente porque um stack cliente mais antigo foi escrito dessa forma. Permita esse padrão, mas conte-o como duas sessões no limite da conta e certifique-se de que o bind receiver esteja realmente aberto antes de presumir que as confirmações estão sendo entregues.

Os limites de sessão importam mais do que se imagina. Um cliente que abre dez binds transceiver “por redundância” ocupa dez posições na tabela de conexões do seu servidor e pode enviar dez vezes a vazão que você pretendia. De duas a quatro sessões por conta é um padrão sensato; um cliente que precisa de mais é um cliente que deveria estar em um pacote superior.

Vazão, janelas e limitação (throttling)

A vazão no SMPP depende de dois fatores: quantas PDUs o cliente pode manter em trânsito antes de aguardar as confirmações de recebimento (a janela) e a taxa que você permite. O guia SMPP versus HTTP explica por que um único bind bem gerenciado pode enviar centenas de mensagens por segundo; o ponto aqui é que, na sua plataforma, é você quem recebe essa carga.

Defina para cada conta SMPP um limite de mensagens por segundo que venha do contrato, e não do que o seu servidor seria capaz de processar. Um cliente que paga por 10 msg/s recebe 10 msg/s; quando ele ultrapassar esse valor, responda com o erro de limitação definido pelo protocolo (ESME_RTHROTTLED), em vez de colocar o excedente em fila sem aviso. Uma biblioteca cliente bem escrita trata esse erro como um pedido para desacelerar e reduz o ritmo. Uma mal escrita continua enviando sem parar, e o seu servidor deve derrubar o bind após violações repetidas e registrar o motivo, porque a alternativa é que o loop de novas tentativas mal configurado de um único cliente se transforme na latência de todos.

Mais dois números devem constar na conta. Um tamanho de janela (de 10 a 20 PDUs sem confirmação é o típico para um bind voltado a clientes; as operadoras, do outro lado da sua plataforma, podem permitir mais) e um intervalo de enquire_link, o heartbeat que mantém ativa uma sessão ociosa. Informe os três ao cliente quando emitir as credenciais. O chamado mais comum do tipo “o SMPP não está funcionando” é uma biblioteca cliente configurada para uma janela que o seu servidor não concede, que atinge o tempo limite a cada décima mensagem e relata isso como falha da plataforma.

Para onde vão as confirmações de entrega

Uma confirmação de entrega (DLR) no SMPP não é uma resposta ao submit do cliente. Ela chega depois, sem ter sido solicitada, como um deliver_sm no bind receiver ou transceiver do cliente, e o cliente a associa à mensagem original pelo ID que o seu servidor devolveu no momento do envio. Disso decorrem três consequências.

Primeira: a confirmação precisa ter para onde ir. Se o cliente está conectado apenas como transmitter e não tem nenhum bind receiver aberto, a confirmação não tem caminho. Defina a política com antecedência: exigir binds transceiver, reter as confirmações por um curto período até que um bind receiver apareça ou oferecer um webhook como canal de confirmações para os clientes que não conseguem operar um receiver. Descartar confirmações silenciosamente é a única opção que certamente vai voltar na forma de uma contestação.

Segunda: a confirmação é sua antes de ser do cliente. A sua plataforma precisa da confirmação da operadora para liquidar a mensagem no livro-razão, exibir o status no console do cliente e alimentar os seus próprios relatórios de qualidade de entrega por rota. Armazene a confirmação, atualize a mensagem e só então a encaminhe. Um desenho que apenas repassa as confirmações ao bind e não guarda nada é um desenho sem resposta quando o cliente diz “vocês me cobraram por 4.000 mensagens que nunca chegaram”.

Terceira: as confirmações chegam aproximadamente na mesma taxa dos envios, e as confirmações de uma campanha chegam depois da campanha. Um cliente que dispara 50.000 mensagens em cinco minutos vai receber 50.000 pacotes deliver_sm ao longo dos dez minutos seguintes. Se o bind receiver dele demorar para confirmar o recebimento, a sua fila de saída de confirmações cresce; faça dela uma fila com profundidade visível, e não um buffer sem limite, e crie alertas pelo tempo de espera, para que um bind de cliente travado apareça no seu painel antes que o cliente abra um chamado.

IDs de remetente, codificação e os erros comuns dos clientes

Uma conta SMPP também precisa de um conjunto de regras. Quais endereços de origem (IDs de remetente) o cliente pode usar, alfanuméricos ou numéricos, e o seu servidor reescreve ou rejeita um ID desconhecido? Quais codificações de dados (GSM 7-bit ou UCS-2 para alfabetos não latinos) e como as mensagens longas são divididas (concatenação por UDH, que a biblioteca do cliente normalmente trata, mas às vezes não)? Que período de validade e que flag de entrega registrada (registered delivery) você exige, para que as confirmações sejam de fato solicitadas?

Essas regras devem ficar na conta e ser aplicadas no momento do submit, com um código de erro claro, em vez de a mensagem ser aceita e depois falhar silenciosamente na operadora. Da mesma forma que uma boa API HTTP retorna um 400 com o motivo, um bom servidor SMPP rejeita o submit_sm com o status correto e permite que o cliente corrija o lado dele. Cada regra aplicada na borda da sua plataforma é uma contestação a menos no futuro.

Faturamento por bind: a conta é dona do livro-razão

Esta é a parte que dá errado quando o servidor SMPP é acoplado ao lado da plataforma, em vez de integrado a ela. Uma mensagem que entra por SMPP precisa ser tarifada e debitada exatamente como uma mensagem que entra pelo console ou pela API HTTP: mesmo plano de tarifas, mesmo saldo, mesma margem registrada na mesma rota. Os três modos de cobrança do guia de faturamento (CreditRoute, WalletRoute e AutoRoute) se aplicam à conta, e o bind os herda. Quando o saldo chega a zero, o servidor SMPP precisa rejeitar o submit com o erro adequado, em vez de aceitar tráfego em uma fila que nunca será paga.

Um bind SMPP é uma porta de entrada para a conta do cliente, e não uma conta separada. Se o livro-razão não enxerga essa porta, ela se torna uma fonte de perda de receita.

Onde o SMPP realmente justifica uma linha comercial própria é no pacote em torno do bind: um compromisso mínimo mensal em troca de um limite de vazão maior, uma taxa por sessão adicional, um valor adicional por uma rota dedicada ou por um short code. Defina o preço desses itens como condições da conta, para que o livro-razão registre a taxa e o tráfego no mesmo extrato, e para que um cliente que migra do HTTP para o SMPP veja uma única fatura com uma linha a mais, e não um novo relacionamento comercial.

Onboarding de um cliente: o pacote de credenciais

Quando um cliente for aprovado para SMPP, envie um único documento, e que seja sempre o mesmo documento:

1. Host, porta e o que esperar quanto ao TLS, se você fizer a terminação TLS na frente do servidor SMPP.
2. system_id e senha (enviados por um canal diferente do e-mail que leva o restante).
3. Modos de bind permitidos e o número máximo de sessões.
4. Os endereços IP dos quais você aceitará binds e como alterá-los.
5. Limite de vazão em msg/s, tamanho da janela, intervalo de enquire_link.
6. IDs de remetente permitidos, regras de codificação, tratamento de mensagens longas, flag de entrega registrada exigida.
7. Para onde vão as confirmações e os códigos de erro que o cliente deve esperar e tratar.
8. A rota de teste e os números de teste a usar antes da entrada em produção.

Metade desses itens são números que o engenheiro do cliente vai digitar em um arquivo de configuração na hora seguinte. Entregá-los todos de uma vez é a diferença entre uma integração de um dia e uma troca de e-mails de duas semanas.

Testes antes da entrada em produção

Nunca ative a conta SMPP de um cliente diretamente nas rotas de produção. Ofereça uma rota de teste que aceite mensagens, gere uma confirmação plausível após um curto intervalo e não cobre nada, e acompanhe o cliente em seis verificações nessa rota: um bind em cada modo permitido; uma única mensagem e a confirmação dela, associada pelo ID; uma mensagem longa em alfabeto não latino chegando como uma única mensagem em um aparelho real; um pico acima do limite de vazão gerando erros de limitação e uma redução de ritmo correta; um ID de remetente propositalmente errado gerando a rejeição esperada; e uma conexão derrubada seguida de uma reconexão limpa. Só então passe a conta para as rotas de produção, e faça isso com o limite ainda ativo.

A mesma rota de teste é a que você usa para reproduzir um problema do cliente mais tarde. Um cliente que diz “as confirmações pararam” pode fazer bind na rota de teste, enviar uma mensagem e ver a confirmação voltar no console, o que transforma um chamado vago em uma verificação de dez minutos do bind receiver dele.

Quando um cliente não deve ter SMPP

Nem todo cliente que pede SMPP deve recebê-lo. Uma equipe de marketing que envia pelo navegador não tem uso para um bind; um desenvolvedor que envia 300 OTPs por dia é mais bem atendido pela API HTTP, que não precisa de sessão persistente e retorna erros que ele consegue ler. O SMPP é para clientes com volume, com um stack SMPP já existente ou com um motivo de conformidade para manter uma relação direta via protocolo. Todos os demais usam a API, e a sua fila de suporte fica mais leve por isso.

O que torna a oferta confiável é que a plataforma por baixo é a mesma e, com uma licença self-hosted, o servidor SMPP está incluído, em vez de ser vendido como um plano separado. Um cliente que começa na API HTTP e evolui para um bind SMPP mantém a conta, o saldo, o plano de tarifas e os relatórios; o bind é mais um canal para uma conta omnicanal que também pode transportar o tráfego de WhatsApp e RCS dele no mesmo livro-razão. Essa continuidade é o que um revendedor que aluga um painel normalmente não consegue oferecer, e é o motivo discreto pelo qual os clientes técnicos permanecem.