Rejeições HTTP em SMS A2P: como distinguir erros de integração de falhas de entrega

O que significa — e o que não significa — uma resposta HTTP

Uma resposta HTTP informa o resultado da comunicação entre o cliente e o endpoint, de acordo com a implementação da API. Por si só, não confirma que o fornecedor aceitou o SMS para processamento nem que a mensagem chegou ao telemóvel.

Numa integração de SMS, convém distinguir três resultados: a resposta do transporte HTTP, a aceitação ou rejeição do pedido de envio pela API e os estados posteriores da mensagem. No SMPP, por exemplo, os relatórios de entrega podem ser comunicados através de mensagens deliver_sm ou data_sm; são mecanismos distintos da resposta HTTP inicial.

O significado de cada resposta depende do contrato da API. Consulte a documentação oficial do fornecedor para saber o que indica o código HTTP, o que o corpo da resposta confirma e como obter o estado posterior da mensagem.

Separe as etapas antes de diagnosticar

Modele o percurso como etapas observáveis, não como um único resultado de «enviado» ou «falhado». Essa separação evita atribuir à rede móvel um problema de autenticação ou interpretar uma aceitação técnica como entrega confirmada.

Transporte HTTP: determine se o seu cliente conseguiu comunicar com o endpoint e que resposta recebeu. Uma falha de ligação ou um timeout não demonstra que a API não processou o pedido.

Validação e aceitação: analise a resposta da API de acordo com a respetiva documentação. Pode indicar que o pedido é inválido, foi rejeitado ou foi aceite para uma etapa posterior; não presuma que todos os fornecedores usam a mesma estrutura ou semântica.

Estado posterior: consulte o mecanismo documentado para conhecer o progresso ou o resultado do SMS, como um relatório de entrega, quando disponível. Um DLR comunicado pela plataforma não deve ser descrito como uma verificação independente da receção no terminal.

Registe o contexto mínimo para reconstruir o caso

Os campos de registo não são universais: o contrato da API e as políticas de segurança determinam que dados existem e durante quanto tempo são conservados. Como base operacional, registe os elementos disponíveis que permitam associar o pedido à resposta e a qualquer estado posterior.

Inclua a hora com o fuso horário, o identificador de correlação do seu sistema e a referência devolvida pela API, se existir. Guarde o método e o endpoint utilizados, o código HTTP, o corpo da resposta relevante e a versão da integração.

Registe o destino no formato normalizado que enviou e os atributos técnicos necessários para reproduzir o pedido, como o tipo de remetente ou a codificação, quando fizerem parte da API. Evite armazenar conteúdo ou dados pessoais que não sejam necessários para o diagnóstico e aplique as regras de acesso e retenção da sua organização.

Não confunda o identificador interno da sua aplicação com uma referência de mensagem do fornecedor. Indique claramente que sistema gerou cada identificador.

• Hora e fuso horário da tentativa.
• Identificador de correlação interno e referência do fornecedor, se tiver sido devolvida.
• Destino normalizado, método e endpoint; proteja os dados sensíveis.
• Código HTTP, resposta da API e resultado da operação de acordo com o contrato.
• Estado posterior disponível e hora em que foi observado.

Classifique o incidente por etapa e evidências

Não transforme uma tabela genérica de códigos num diagnóstico definitivo. Os intervalos de códigos HTTP dão contexto sobre a resposta do servidor, mas a causa e a ação correta devem ser verificadas na documentação da API e confrontadas com o corpo da resposta.

Conectividade: se não houver resposta HTTP, verifique a resolução do endpoint, a ligação a partir do ambiente de envio, os tempos de espera e os registos disponíveis em ambos os lados. A ausência de resposta não prova que o servidor não recebeu o pedido.

Autenticação e autorização: se a resposta ou o corpo indicar problemas de credenciais ou permissões, confirme o mecanismo de autenticação, o ambiente e as permissões configuradas. Não inclua segredos em pedidos de suporte nem em registos partilhados.

Formato e validação: se a API rejeitar parâmetros, compare o pedido com o esquema oficial: campos obrigatórios, formato do destino e restrições documentadas. Corrija o pedido antes de o enviar novamente.

Limites ou políticas: se a documentação ou a resposta identificar um limite, uma quota ou uma restrição, confirme o respetivo âmbito com o fornecedor. Não deduza uma taxa permitida com base numa resposta isolada.

• Identifique primeiro a etapa em que surgem as evidências: transporte, validação, aceitação ou estado posterior.
• Interprete em conjunto o código HTTP e o corpo da resposta, não apenas um deles.
• Registe que conclusão está confirmada e qual continua a ser uma hipótese.

Timeout: resultado incerto, não rejeição confirmada

Se o cliente exceder o tempo de espera, pode não saber se o pedido chegou ao servidor ou se este o processou antes de a resposta se perder. Sem uma semântica de idempotência documentada, o reenvio pode criar uma segunda tentativa e, potencialmente, uma mensagem duplicada.

Antes de tentar novamente, procure uma referência ou uma consulta de estado documentada pela API para essa operação. Verifique os registos do sistema de envio e, se possível, peça ao fornecedor que confirme se recebeu o pedido original. Não invente uma chave de idempotência nem presuma que repetir a chamada é inofensivo.

• Sem resposta e sem evidências de receção: classifique o resultado como desconhecido, não como rejeição comprovada.
• Resposta explícita de rejeição, interpretada de acordo com a documentação: corrija a causa antes de tentar novamente.
• Aceitação confirmada, mas sem estado posterior: investigue a consulta de estado ou o mecanismo de relatórios antes de enviar novamente.

Procedimento de diagnóstico reproduzível

Trabalhe com um caso autorizado e controlado, respeitando o consentimento e as regras aplicáveis ao tráfego. O objetivo é isolar a etapa com falhas, não aumentar o volume nem testar destinos sem autorização.

1. Guarde o pedido e a resposta observados, protegendo as credenciais e os dados pessoais. Confirme que o cliente não está a descartar o código HTTP nem a substituir a resposta por uma mensagem genérica.

2. Consulte o contrato e a documentação oficial da versão da API utilizada. Confirme o significado do código, os campos da resposta, as referências de mensagem, o mecanismo de estado e as regras de tentativa novamente e de idempotência que estejam documentadas.

3. Compare o pedido real com um pedido válido segundo o esquema publicado. Altere uma variável de cada vez e reproduza apenas através de um fluxo autorizado.

4. Correlacione a hora e os identificadores com os registos do sistema de envio e do fornecedor. Distinga os factos observados das inferências, por exemplo, «resposta HTTP recebida» versus «mensagem aceite» ou «DLR recebido».

Decida entre corrigir, tentar novamente ou escalar

Corrija a integração quando as evidências e a documentação apontarem para credenciais, permissões, formato ou parâmetros incorretos. Não escale como falha de entrega algo que ainda não passou pela validação da API.

Tente novamente apenas quando o contrato da API e as evidências permitirem determinar que é seguro. Se a operação puder ter sido processada e não existir uma garantia documentada contra duplicados, resolva primeiro a incerteza através da referência, da consulta de estado ou do apoio do fornecedor.

Escale quando o problema persistir com um pedido conforme e autorizado, ou quando as evidências situarem o incidente no serviço ou numa etapa posterior sob responsabilidade do fornecedor. Partilhe a hora, o fuso horário, os identificadores, o endpoint, o código HTTP e a resposta relevante; oculte os segredos e limite os dados do destinatário ao estritamente necessário.

• Corrigir: rejeição atribuível a um pedido ou configuração que possa verificar.
• Tentar novamente: apenas segundo uma regra documentada e sem duplicar um resultado incerto.
• Escalar: fornecer evidências correlacionáveis que situem o incidente fora da integração do sistema de envio.

O que não concluir de um 2xx, de um erro ou da falta de DLR

Um HTTP 2xx não confirma automaticamente a entrega do SMS: pode indicar um resultado HTTP bem-sucedido cujo âmbito exato é definido pela API. Verifique se o corpo confirma a aceitação e como são comunicados os estados posteriores.

Uma resposta HTTP de erro também não identifica, por si só, a causa final. Pode estar relacionada com o transporte, a autenticação, a validação ou outra condição específica da implementação; consulte a resposta e a documentação oficial.

A ausência de um DLR não demonstra, por si só, nem entrega nem falha. Determine se o relatório está disponível, qual é o seu significado nesse serviço e se existem informações suficientes para o associar à mensagem. Distinga sempre o estado comunicado pela plataforma de uma confirmação independente de receção no dispositivo.