Contrato de integração de DLR A2P SMS: campos, estados e alterações
Um guia prático para acordar o formato dos DLR entre fornecedores de SMS, preservar os códigos originais, correlacionar eventos e testar alterações sem interpretar um relatório como prova automática de receção no telemóvel.
Porque a semântica de um DLR pode variar
Um relatório de entrega (DLR, na sigla em inglês) é um evento comunicado por um sistema da cadeia de mensagens. O seu significado operacional depende de quem o gera, da etapa que representa e da forma como esse fornecedor define os estados. Por isso, dois sistemas podem usar etiquetas semelhantes sem que os respetivos relatórios constituam provas equivalentes.
Antes de integrar, identifica cada elo envolvido — por exemplo, a plataforma de envio e o fornecedor que devolve o relatório — e solicita a documentação técnica atualizada. Não pressuponhas que um estado, código ou carimbo temporal tem o mesmo significado em todos os sistemas. A informação disponível aqui não permite estabelecer uma lista universal de estados nem as respetivas equivalências.
- Acorda que evento cada fornecedor comunica e que etapa do percurso pretende representar.
- Regista a definição do estado de acordo com a documentação do fornecedor, e não apenas a sua etiqueta.
- Esclarece o significado dos carimbos temporais e o fuso horário utilizado.
Define um esquema comum antes de ligar os sistemas
O contrato de dados deve distinguir os campos obrigatórios, opcionais e condicionados à disponibilidade do fornecedor. Para cada campo, especifica o nome, o tipo, o formato, o significado, as regras para valores em falta e exemplos acordados. Não transformes uma convenção local num requisito universal: valida cada ponto com os participantes na integração.
Como base para a negociação, considera um identificador de evento, o identificador da mensagem conhecido pelo emissor, o estado normalizado, o código e o texto originais, o sistema de origem e os carimbos temporais disponíveis. Acrescenta identificadores de correlação quando existam traduções entre sistemas. A informação disponível não estabelece que todos estes campos existam ou tenham um formato padrão em todos os DLR.
- Marca como obrigatório apenas aquilo que todos os participantes consigam produzir e validar.
- Define se um campo em falta deve ser omitido, representado como nulo ou comunicado através de outro mecanismo.
- Especifica o formato e o fuso horário de cada carimbo temporal; não deduzas a hora de receção a partir de outro carimbo sem uma regra documentada.
- Inclui exemplos válidos e inválidos no contrato.
Preserva o estado normalizado e a resposta original
A normalização facilita o processamento comum, mas pode ocultar diferenças importantes se substituir por completo a resposta do fornecedor. Guarda separadamente o estado interno normalizado e o estado, o código e o texto recebidos originalmente. Preserva também o nome ou identificador do sistema de origem e a versão do mapeamento aplicado.
Mantém uma tabela explícita de correspondências, revista com cada fornecedor. Se um código não estiver documentado ou não puder ser mapeado com segurança, classifica-o como desconhecido ou pendente de análise; não o convertas automaticamente em sucesso ou falha. Em termos operacionais, a normalização deve ser reversível: a equipa tem de conseguir consultar o valor recebido e a regra que produziu a classificação.
- Não descartes o código original ao calcular métricas ou atualizar estados internos.
- Documenta cada equivalência, incluindo a respetiva fonte, âmbito e data de revisão.
- Define uma categoria de desconhecido e um processo de revisão para novos valores.
- Evita agrupar estados distintos, a menos que o fornecedor confirme que representam a mesma condição.
Correlaciona cada evento com o envio correto
Um identificador de mensagem pode ser diferente em sistemas distintos. O contrato deve explicar que identificador cada participante gera, onde é devolvido e como se relaciona com o identificador conhecido pela aplicação que enviou a mensagem. Se houver uma tradução, regista a relação entre os valores, em vez de pressupor que são intercambiáveis.
Define a chave ou a combinação de chaves que a tua integração utilizará para encontrar o envio associado. Especifica o que acontece se faltar um identificador, se não houver correspondência ou se surgirem várias correspondências. Não atribuas um DLR com base apenas numa semelhança de dados que não tenha sido acordada como critério válido.
- Documenta o percurso dos identificadores desde o envio até ao relatório.
- Testa correspondências válidas, bem como identificadores em falta, desconhecidos e repetidos.
- Preserva os valores de origem e de destino de cada tradução.
- Encaminha os eventos sem correspondência para uma fila ou processo de investigação, sem os atribuir arbitrariamente.
Gere duplicados, atrasos e eventos não reconhecidos
Acorda como identificar e tratar eventos repetidos, atrasados ou recebidos por uma ordem diferente da esperada. A informação técnica disponível não define uma regra universal de deduplicação ou sequenciação para todos os fornecedores. Por isso, o contrato deve especificar que dados permitem reconhecer uma repetição, durante quanto tempo a informação necessária é conservada e como se resolvem eventos contraditórios.
Não substituas um estado anterior apenas porque outro evento chegou mais tarde: a ordem de receção pode não corresponder à ordem em que os eventos ocorreram. Determina com cada fornecedor que carimbos temporais são relevantes e que precedência, se existir, está documentada. Se não houver uma regra verificável, preserva o histórico e encaminha os casos ambíguos para revisão.
- Define o critério para identificar duplicados e o que acontece quando um evento é recebido mais de uma vez.
- Regista separadamente o momento da receção local e os carimbos temporais comunicados, se estiverem disponíveis.
- Estabelece como tratar estados atrasados, desconhecidos, contraditórios e sem correspondência.
- Garante que a lógica de atualização é rastreável e evita eliminar o histórico original.
Testa o contrato com casos de aceitação acordados
Prepara testes conjuntos com exemplos aprovados pelos participantes. O objetivo é verificar o formato recebido, a validação dos campos, o mapeamento dos estados e a correlação; não é, por si só, demonstrar que um telemóvel recebeu a mensagem. A lista de códigos e resultados esperados deve basear-se na documentação e no acordo técnico dos fornecedores envolvidos.
Executa os testes num ambiente adequado e regista os dados de entrada, o resultado esperado, o resultado observado e a decisão. Se o formato real diferir do contrato ou um estado não estiver documentado, suspende a aceitação dessa variante até a discrepância ser resolvida.
- Evento válido com todos os campos acordados.
- Campo opcional em falta e campo obrigatório em falta, cada um com o comportamento esperado documentado.
- Estado conhecido, com o código original preservado e o mapeamento esperado.
- Código ou estado desconhecido, sem classificação automática como sucesso.
- Evento repetido, atrasado, fora de ordem e sem identificador correlacionável.
- Formato com campos acrescentados, omitidos ou renomeados, ou com um tipo diferente, de acordo com os limites do contrato.
Controla as versões do contrato e as alterações
Trata o formato e o mapeamento como um contrato partilhado, não como uma suposição implícita no código. Identifica cada versão, conserva o histórico de alterações e comunica que sistemas a aceitam. Antes de implementar uma modificação, determina se afeta a estrutura, o tipo de um campo, a semântica de um estado ou a correlação.
Acorda com cada participante um processo de notificação, revisão e teste. Não declares uma alteração compatível apenas porque a mensagem continua sintaticamente válida: uma etiqueta inalterada pode adquirir outro significado, e um campo acrescentado pode afetar consumidores que validam o formato de forma estrita. A compatibilidade deve ser verificada face às regras específicas da integração.
- Atribui uma versão identificável ao contrato e às tabelas de mapeamento.
- Avalia separadamente as alterações de formato e as alterações semânticas.
- Executa os casos de aceitação acordados antes de ativar uma nova versão.
- Define como comunicar, aceitar ou rejeitar alterações incompatíveis.
Um DLR comunicado não prova, por si só, a receção no terminal
Interpreta o DLR dentro do âmbito documentado pelo emissor. Um estado comunicado por um elo indica o que esse sistema reporta; não deve ser apresentado automaticamente como confirmação independente de que a mensagem apareceu ou foi recebida pelo utilizador no terminal. A informação disponível não permite afirmar que um estado específico garanta essa receção.
Nos relatórios operacionais, distingue os eventos recebidos de qualquer verificação independente disponível e descreve os seus limites. Não uses o DLR como prova de consentimento, identidade ou leitura da mensagem. Se uma decisão de negócio depender da receção efetiva, define previamente que evidência será considerada suficiente e consulta as capacidades documentadas dos sistemas envolvidos.
- Descreve o estado como comunicado pela sua origem e não como um facto mais abrangente do que o sustentado pela documentação.
- Separa a receção do DLR, o estado normalizado e qualquer evidência independente disponível.
- Apresenta os casos desconhecidos ou ambíguos nas métricas e nos relatórios, em vez de os forçar a uma categoria conclusiva.
Perguntas frequentes
Existe uma lista universal de estados DLR que todos os fornecedores devam utilizar?
A informação técnica disponível para este guia não permite estabelecer uma lista universal nem equivalências entre fornecedores. Solicita a documentação de cada participante e acorda explicitamente os estados e códigos a mapear.
Devo substituir o código original por um estado normalizado?
Não. Preserva o código, o texto e a origem originais juntamente com o estado normalizado e a regra de mapeamento aplicada. Assim, podes investigar discrepâncias e rever o mapeamento quando a documentação mudar.
O que devo fazer com um DLR duplicado ou sem correspondência?
Define por contrato como reconhecer e registar duplicados. No caso de um evento sem correspondência, preserva os dados recebidos e encaminha-o para investigação; não o atribuas a um envio com base numa correspondência que não tenha sido acordada.
Um DLR confirma que o SMS chegou ao telemóvel?
Não necessariamente. O DLR comunica o estado reportado por um sistema da cadeia, e o seu âmbito depende da definição do emissor. Não o apresentes como prova independente de receção no terminal sem evidência documentada que o sustente.
O que deve ser testado antes de aceitar uma alteração de formato?
Verifica os campos obrigatórios e opcionais, os tipos e formatos acordados, a preservação dos valores originais, o mapeamento de estados, a correlação e o tratamento de valores desconhecidos, repetidos e atrasados. Os participantes devem documentar o resultado esperado.
Fontes consultadas
- SMPP v3.4 Issue 1.2SMPP Developers Forum
- HTTP Semantics (RFC 9110)IETF
- 3GPP specifications by series3GPP
- ITU-T Recommendation E.164International Telecommunication Union
- GSMA Networks resourcesGSMA