Eventos duplicados e fora de ordem em SMS A2P: como reconciliá-los sem perder evidências

Por que os eventos podem ser duplicados, atrasados ou chegar fora de ordem

Numa integração A2P, um envio pode gerar observações em mais de uma etapa: o pedido à API, uma resposta de aceitação ou rejeição, uma interação SMPP e, se estiver disponível, um relatório de entrega (DLR). Esses sinais não chegam necessariamente ao mesmo tempo nem pela ordem em que os acontecimentos ocorreram. Também podem existir novas tentativas de notificação ou eventos repetidos.

A semântica concreta depende da interface e do fornecedor. Não existe uma precedência universal que permita concluir, para todos os sistemas, que um evento de API prevalece sobre um de SMPP ou que qualquer DLR significa a mesma coisa. Documente o que cada evento representa na sua integração antes de o utilizar para atualizar um estado.

• Separe o momento em que o sistema afirma que um evento ocorreu do momento em que a sua plataforma o recebeu.
• Trate as mensagens repetidas como uma possibilidade operacional, não como prova de que o acontecimento subjacente ocorreu várias vezes.
• Não assuma que a ausência de um evento equivale a falha, entrega ou cancelamento.

Separe o registo original da vista de estado calculada

Mantenha dois conceitos distintos. O registo de eventos conserva o que foi recebido; a projeção operacional resume o que a plataforma pode afirmar neste momento. Se uma regra de reconciliação mudar, a projeção pode ser recalculada a partir do registo, sem apagar nem reescrever as evidências que originaram o resultado.

Para cada evento, conserve, quando disponíveis, o conteúdo recebido, a fonte ou interface, o identificador de correlação, os tempos declarados e observados e o resultado das validações. Evite substituir um evento anterior por outro posterior apenas porque este último parece mais conclusivo.

A retenção, a proteção contra alterações e os requisitos de auditoria devem estar de acordo com as obrigações da sua organização e os contratos aplicáveis. Não existe aqui uma garantia universal de armazenamento imutável.

• Guarde a observação original e registe separadamente qualquer normalização.
• Versione as regras utilizadas para calcular a projeção.
• Permita reconstruir quais eventos e regras produziram o estado apresentado.

Defina a identidade e a deduplicação sem assumir uma chave global

Não parta do princípio de que existe um identificador único partilhado entre API, SMPP, agregadores e operadores. Um identificador pode ser válido apenas numa conta, ligação, fornecedor ou período. Defina o âmbito de cada identificador de acordo com a documentação da interface concreta.

Se não existir uma chave fiável, não associe eventos apenas porque coincidem o destinatário, o texto e uma hora aproximada: duas mensagens legítimas podem partilhar esses atributos. Nesse caso, conserve ambas e assinale-as como possíveis duplicados ou como uma correlação incerta, em vez de descartar evidências.

A normalização do número pode facilitar as pesquisas, mas não prova, por si só, que dois registos correspondem ao mesmo envio. A norma E.164 é uma recomendação de numeração; não fornece, por si só, uma regra de correlação de mensagens.

• Use primeiro o identificador documentado pela interface e o respetivo âmbito: conta, ligação ou fornecedor.
• Registe as regras de deduplicação e o motivo de cada correspondência.
• Se a correlação for ambígua, conserve o evento e evite fundir mensagens automaticamente.

Ordene com cautela: tempo declarado, tempo observado e sequência

Conserve separadamente a marca temporal incluída pelo emissor do evento e a hora em que o seu sistema o observou. Uma hora declarada pode descrever o momento de origem; a hora observada regista quando o evento chegou à sua plataforma. Uma não deve substituir silenciosamente a outra.

Se a interface fornecer uma sequência ou versão com semântica documentada, avalie a possibilidade de a utilizar dentro do âmbito para o qual é válida. Se não existir um sinal de ordenação fiável, não transforme a ordem de chegada numa cronologia definitiva. Uma regra estável para desempates pode tornar o cálculo repetível, mas não prova o que aconteceu primeiro.

Registe o fuso horário, a precisão e possíveis problemas do relógio quando esses dados estiverem disponíveis. Se faltarem, mantenha essa limitação na avaliação do evento.

• Guarde pelo menos o tempo declarado e a hora de receção em campos distintos.
• Aplique sequências apenas se conhecer o respetivo âmbito e significado.
• Assinale como incerta a ordem relativa quando as evidências não permitirem determiná-la.

Defina transições explícitas e não infira entregas

Conceba uma máquina de estados para o seu sistema com base nos significados documentados para cada interface. Não existe uma precedência universal entre aceitação, erro, estado intermédio e DLR que possa ser aplicada sem conhecer o fornecedor e o contrato técnico.

Uma aceitação de envio indica apenas o que a interface documenta sobre o pedido. Um DLR deve ser interpretado de acordo com a sua origem e semântica; a sua receção não equivale automaticamente a uma verificação independente de que a pessoa viu o SMS ou de que, em todos os casos, a mensagem chegou ao dispositivo.

Quando as evidências não forem suficientes para decidir, apresente um estado como «pendente», «desconhecido» ou «em conflito», de acordo com o seu modelo. O nome deve deixar claro que não se trata de uma entrega confirmada.

• Documente quais eventos permitem cada transição e o que significam nessa integração.
• Defina condições para manter um estado incerto e para assinalar uma contradição.
• Não transforme a ausência de DLR, uma aceitação ou um código não interpretado numa entrega confirmada.

Trate contradições e DLR tardios sem perder o histórico

Se um DLR chegar depois de a interface ter comunicado uma falha, ou se duas fontes parecerem contradizer-se, conserve ambos os eventos e avalie o seu significado de acordo com a documentação aplicável. Não elimine o evento antigo nem escolha automaticamente o mais recente: a hora de receção, por si só, não determina qual tem maior autoridade.

A projeção pode ser atualizada quando uma nova observação acrescenta evidências relevantes, mas deve ficar registado o que mudou, quando foi recalculada e com que regra. Se o conflito não puder ser resolvido, é mais rigoroso mantê-lo visível do que o ocultar por trás de um único estado definitivo.

• Registe as contradições como uma condição explícita, não como uma substituição silenciosa.
• Defina quando uma regra permite resolver um conflito e quando é necessária uma revisão.
• Conserve os eventos tardios para auditoria e reprocessamento.

Torne a reconciliação repetível e auditável

Um reprocessamento deve produzir o mesmo resultado se for executado com o mesmo conjunto de eventos, as mesmas regras e a mesma versão da configuração. Para se aproximar dessa propriedade, separe a ingestão da projeção e evite que o resultado dependa de efeitos secundários não registados.

A idempotência pode ser aplicada ao processamento de uma notificação quando existe uma identidade fiável e um âmbito definido. Se estes não existirem, uma deduplicação agressiva pode descartar evidências válidas. É preferível registar o critério utilizado, conservar a observação recebida e assinalar as correspondências incertas.

Monitorize padrões anómalos, como aumentos de eventos repetidos, atrasos invulgares entre tipos de eventos ou contradições recorrentes. Os alertas devem descrever o que foi observado; não atribua uma causa sem evidências.

• Versione as regras de projeção e registe a versão aplicada.
• Permita recalcular os estados a partir do histórico conservado.
• Meça duplicados, atrasos e conflitos por interface e âmbito, sem os transformar em garantias de qualidade.

Exemplo: aceitação, falha temporária e DLR tardio

Suponha que a API responde com a aceitação do pedido. Mais tarde, chega um sinal que a sua integração interpreta como uma falha temporária e, depois, aparece um DLR. Os nomes e significados exatos devem provir da documentação desse fornecedor; este exemplo não estabelece uma sequência normativa.

Primeiro, conserve os três eventos, com os respetivos tempos declarados e de receção, identificadores e âmbito conhecido. Verifique se podem ser correlacionados com segurança. Em seguida, aplique as regras documentadas: a aceitação não prova a entrega, a falha temporária não deve ser apagada pela chegada posterior de outro evento e o DLR só pode elevar o grau de certeza até ao limite permitido pela sua semântica.

Se a documentação estabelecer que esse DLR representa um resultado de entrega para a mensagem correlacionada, a projeção pode refletir esse resultado com o seu âmbito claramente indicado. Se a semântica, a identidade ou a relação com o envio não estiverem confirmadas, mantenha o estado como incerto ou em conflito. Em nenhum caso o exemplo permite afirmar que o utilizador viu o SMS ou que houve uma receção independente no telemóvel.

• Conclua que foram recebidos uma aceitação, um sinal de falha e um DLR; a correlação e o significado têm de ser verificados.
• Não conclua sem documentação que a aceitação confirma a entrega ou que o DLR prova a receção efetiva pelo utilizador.
• Mantenha pendente qualquer conflito de identidade, ordem ou semântica que as evidências disponíveis não resolvam.