Contrato de dados operacionais de SMS A2P: campos e semântica

O que resolve um contrato de dados operacionais

No tráfego de SMS A2P — mensagens enviadas de uma aplicação ou sistema para uma pessoa — várias organizações podem registar a mesma mensagem em momentos diferentes e com vocabulários distintos. Um contrato de dados operacionais reduz ambiguidades ao especificar o significado de cada campo, quem o comunica e como os eventos se relacionam.

Não é uma norma universal nem garante a entrega. É um acordo entre as partes para trocar e conciliar informações. Deve distinguir as decisões tomadas no âmbito do próprio acordo dos requisitos de uma interface ou especificação técnica aplicável. As referências normativas, como SMPP ou HTTP, devem ser consultadas diretamente antes de lhes atribuir requisitos concretos.

• Acordar o esquema antes de integrar ou alterar a troca de dados.
• Documentar definições, formatos, vocabulários e responsabilidades juntamente com os campos.
• Tratar a interpretação dos estados como um acordo explícito, não como uma equivalência presumida entre sistemas.

Intervenientes e limites de responsabilidade

Uma cadeia pode incluir a empresa que origina o tráfego, uma plataforma de mensagens, um ou vários fornecedores e uma operadora móvel. A rota concreta e a participação de cada entidade dependem do acordo e da configuração do serviço; não se deve presumir que a cadeia é idêntica em todos os casos.

Para cada dado, indiquem quem o gera, quem o transmite, quem pode transformá-lo e quem é responsável pela sua interpretação. Por exemplo, o emissor pode declarar o tipo de tráfego; uma plataforma pode atribuir um identificador interno; e um fornecedor pode comunicar um estado recebido de outro sistema. Estas são possíveis atribuições de conceção, não responsabilidades universais.

Separar responsabilidades ajuda a investigar discrepâncias: uma parte pode confirmar que aceitou um pedido sem afirmar que a rede o entregou, enquanto outra pode comunicar um resultado posterior, dentro dos limites permitidos pela respetiva fonte.

• Atribua um responsável a cada campo e a cada transição de estado.
• Declare onde termina a responsabilidade de cada parte pela informação comunicada.
• Inclua um contacto e um procedimento para conciliar discrepâncias, sem presumir que todas as partes observam os mesmos eventos.

Campos mínimos e significado

O conjunto mínimo depende do objetivo: operações, suporte, conciliação ou análise. Convém começar pelos dados necessários para correlacionar um pedido com os eventos subsequentes e acrescentar apenas campos que as partes consigam produzir e utilizar de forma definida.

Documente, no mínimo, um identificador de mensagem por sistema e, quando aplicável, os identificadores de correlação entre sistemas. Inclua o destinatário no formato acordado, o remetente, a classificação declarada do tráfego — por exemplo, OTP, transacional ou marketing — e a rota declarada, se for conhecida. Não apresente uma rota declarada como prova independente da rota efetivamente percorrida.

Também convém incluir o estado, a origem do estado, o carimbo temporal do evento e o código de erro, quando existir. Se for partilhada a operadora de destino, indiquem como foi identificada e quando. Um campo de operadora desconhecida não deve ser preenchido por inferência. Definam também a versão das condições ou do acordo operacional aplicável, com o respetivo identificador e a data ou período de vigência acordado.

• Identificadores: identificador da mensagem no sistema emissor e referências de correlação disponíveis.
• Contexto: destinatário, remetente, classificação do tráfego, rota declarada e operadora, quando conhecida.
• Evento: estado, origem do estado, data e hora, código de erro e versão das condições.
• Para cada campo, especifique o tipo, o formato, a obrigatoriedade, o vocabulário e o significado.

Estados: aceitação, envio, DLR e resultado desconhecido

Não reduza todo o ciclo a um único campo genérico de «estado». Defina as etapas que o acordo precisa de distinguir: por exemplo, pedido aceite por uma interface, tentativa de envio comunicada por uma parte, relatório de entrega recebido ou resultado ainda desconhecido. Os nomes exatos e as transições devem ser acordados para cada integração.

Um DLR é um relatório de estado recebido de uma determinada fonte. Registe quem o emitiu ou transmitiu e o que significa nesse contexto. Não o trate, por si só, como verificação independente de que a mensagem apareceu no terminal ou foi lida pela pessoa.

Mantenha o estado como desconhecido quando não houver informação suficiente para chegar a uma conclusão. Não transforme automaticamente a ausência de um DLR numa falha, nem um estado favorável comunicado numa garantia de receção. Se duas fontes discordarem, conserve ambos os eventos e documente qual deles cada processo utiliza e porquê.

• Defina cada estado com uma descrição, a entidade que o comunica e as transições permitidas.
• Separe o estado comunicado da avaliação interna que uma parte faça do caso.
• Conserve os eventos originais para reconstruir a sequência e resolver discrepâncias.

Carimbos temporais e ordem dos eventos

Um carimbo temporal deve permitir compreender quando o evento ocorreu ou foi registado e em que fuso horário. Acordem o formato, a precisão disponível e se a data representa o momento do evento, o momento em que o relatório foi recebido ou o momento em que foi registado no sistema.

Não deduza a ordem apenas pela hora de chegada a uma plataforma: os eventos podem ser recebidos numa ordem diferente daquela que cada parte lhes atribui. Mantenha identificadores de evento ou sequências, se estiverem disponíveis, e registe separadamente os carimbos temporais de origem e de receção quando necessário para a conciliação.

Se uma fonte não fornecer fuso horário ou precisão suficiente, declare-o. Não preencha esses dados como se tivessem sido observados.

• Acordar o formato da data e hora, o fuso horário e a precisão.
• Distinguir a hora do evento, a hora de receção e a hora de processamento.
• Definir como ordenar eventos quando os carimbos temporais coincidirem ou forem incompletos.

Origem dos dados e nível de evidência

O mesmo valor pode ter um peso diferente consoante quem o declarou e como foi obtido. Acrescente metadados de proveniência quando ajudarem a interpretar o registo: sistema de origem, parte que o transmite, momento da observação e indicação de que se trata de um dado declarado, de um evento recebido ou de uma observação independente.

Por exemplo, uma rota pode ser declarada por uma plataforma, enquanto um estado pode chegar num relatório de um fornecedor. O contrato deve impedir que a transformação ou agregação elimine essa distinção. Se não existir verificação independente, indique-o em vez de a sugerir.

Estabeleça também que evidências são aceites para cada utilização: suporte, conciliação ou análise. O valor que serve para investigar pode não ser suficiente para resolver uma disputa comercial.

• Indique a proveniência do dado e a parte que o comunicou.
• Distinga observação direta, declaração e evento recebido.
• Não transforme um estado transmitido numa afirmação mais forte do que a fonte disponível permite.

Valores nulos, vocabulários e códigos de erro

Um campo vazio pode significar que o valor é desconhecido, não foi recolhido, não se aplica ou não foi recebido. O contrato deve distinguir estes casos em vez de deixar que cada sistema os interprete à sua maneira. Se o formato de troca não permitir representar essas diferenças, documentem uma convenção comum e os seus limites.

Definam vocabulários controlados para categorias e estados e acordem como tratar valores específicos de um fornecedor. Conservem o código original juntamente com uma categoria normalizada, se for necessário comparar dados entre partes. A normalização não deve apagar o valor que permite investigar o evento na sua fonte.

Antes de acrescentar códigos, estados ou remetentes a uma lista acordada, indiquem quem os pode propor, como são documentados e a partir de quando se aplicam. Não reutilizem um valor antigo com um novo significado.

• Distinguir explicitamente desconhecido, ausente, não aplicável e não recebido.
• Manter o valor original e, quando acordado, acrescentar um valor normalizado.
• Publicar definições e exemplos para códigos proprietários, sem os apresentar como universais.

Versionamento e alterações do esquema

Cada troca deve permitir identificar que versão do esquema e que versão das condições operacionais foram aplicadas. Acordem como essa versão é comunicada e como se relaciona com o período do tráfego, em vez de presumir que o nome de uma interface basta para identificar as regras.

Definam antecipadamente um processo de alteração: quem propõe modificações, quem as aprova, como são testadas e quando entram em vigor. Uma alteração que acrescenta um campo opcional pode ser mais fácil de adotar do que uma que muda o significado de um estado ou torna um dado obrigatório; classifiquem o impacto tendo em conta os consumidores reais.

Durante uma transição, indiquem que versões podem coexistir, como os registos são identificados e durante quanto tempo se mantém a compatibilidade, se as partes acordarem um prazo. Evitem alterar a semântica sem mudar a versão ou sem comunicar a alteração de forma inequívoca.

• Versionar o esquema e registar a versão das condições aplicáveis.
• Classificar as alterações de acordo com o impacto nos produtores, consumidores e processos de conciliação.
• Acordar a aprovação, os testes, a data de entrada em vigor e o tratamento das versões anteriores.