Alterações na integração HTTP e SMPP para SMS A2P: como validar a compatibilidade antes da implantação

Que alterações justificam uma regressão e o que fica fora do seu âmbito

Uma regressão de integração verifica se uma alteração modificou o contrato técnico entre uma aplicação e a sua interface de SMS. É conveniente executá-la quando se altera a aplicação cliente, o conector, a configuração de transporte ou a forma como as respostas e os estados são interpretados. HTTP e SMPP são interfaces distintas: um teste bem-sucedido numa delas não valida automaticamente a outra.

O âmbito deve ser explícito. Uma resposta HTTP satisfatória confirma o resultado do pedido segundo a semântica HTTP, não a entrega do SMS ao dispositivo. Do mesmo modo, estabelecer uma sessão SMPP ou receber uma resposta a uma operação de envio não demonstra, por si só, que o destinatário recebeu a mensagem. A entrega e o significado dos estados posteriores dependem das evidências disponíveis e da documentação aplicável.

• Inclui: compatibilidade dos pedidos, campos, codificação acordada, interpretação das respostas, correlação de identificadores e tratamento de desconexões.
• Trata separadamente: aceitação técnica, evolução posterior da mensagem e receção comprovada num terminal.
• Não uses um teste de integração como substituto de uma avaliação da rota, da cobertura ou da qualidade da entrega.

Contrato técnico: campos, codificação, remetente, referências e semântica

Antes de escrever testes, converte a documentação atual da API ou do fornecedor SMPP num contrato verificável. A documentação genérica não permite assumir que campos são obrigatórios, como o remetente é expresso, que codificação é aceite, que formato tem um identificador ou que estados são devolvidos. Regista cada regra e a respetiva fonte, e confirma qualquer ponto ambíguo com a especificação ou o fornecedor correspondente.

Para cada campo, indica se é obrigatório ou opcional, o respetivo formato, os limites documentados, o valor predefinido, se existir, e o comportamento esperado quando está em falta ou é inválido. Quanto à codificação, define os casos de texto permitidos pelo contrato e como verificarás que o conteúdo recebido pela interface mantém o significado esperado. Não pressuponhas que dois conectores interpretam da mesma forma os caracteres, os remetentes ou as referências.

Define também a semântica das respostas: o que significa a aceitação ou a rejeição nessa interface, que identificador é devolvido e como se correlaciona com o estado posterior. Em SMPP, utiliza a especificação da versão acordada e a implementação contratada para interpretar operações, respostas, campos e estados; não infiras detalhes de uma integração com base na documentação de outra.

• Mantém uma tabela por interface com o campo, a regra documentada, a validação e o resultado esperado.
• Separa o identificador do pedido do identificador da mensagem, caso o contrato os distinga; documenta o respetivo âmbito e utilização.
• Guarda exemplos representativos e seguros, sem dados pessoais reais nem credenciais, para repetir os testes.

Casos de teste HTTP e SMPP: aceitação, rejeição e recuperação

Cria um conjunto de testes por interface. Para HTTP, verifica pedidos válidos e dados que o contrato define como inválidos; confirma que a aplicação interpreta corretamente a resposta e preserva a correlação necessária. Os códigos de estado HTTP descrevem o resultado da interação HTTP de acordo com a RFC 9110, mas o seu significado para o envio de SMS deve ser obtido no contrato da API.

Para SMPP, testa separadamente a ligação e as operações de envio definidas para a versão e o fornecedor utilizados. Verifica a resposta do protocolo e o tratamento das rejeições documentadas. A especificação SMPP v3.4 serve de referência para as operações e respostas dessa versão, mas os detalhes concretos que deves esperar dependem do contrato aplicável.

Acrescenta cenários de timeout, desconexão e recuperação, mas não imponhas um comportamento universal. Define primeiro o que o contrato estabelece sobre tentativas repetidas, pedidos cujo resultado é desconhecido e reconexão. Se não existir uma regra documentada, regista o caso como uma decisão pendente, em vez de transformar uma suposição num critério de aprovação.

• Testa a aceitação técnica com dados de teste autorizados e um destino controlado.
• Inclui rejeições esperadas e confirma que o sistema não as regista como aceitação.
• Simula timeouts e desconexões num ambiente controlado; verifica o comportamento acordado e guarda as evidências.
• Não voltes a enviar automaticamente uma mensagem cujo resultado seja incerto, salvo se o contrato e a conceção da aplicação definirem como evitar consequências indesejadas.

Callbacks e estados correlacionados: o que demonstra um DLR

Se a integração utilizar callbacks ou notificações de estado, testa todo o percurso entre a aceitação inicial e o evento posterior definido pelo contrato. Verifica se a notificação pode ser associada ao envio correto através dos identificadores documentados e se a aplicação distingue entre ausência de evento, evento recebido e estado final comunicado.

Não pressuponhas que um callback tem os mesmos campos, ordem ou semântica em todos os fornecedores. Compara o formato, a autenticidade, a repetição e o tratamento de eventos tardios com a documentação da integração. Se algum aspeto não estiver especificado, delimita-o como uma incerteza e acorda como será observado operacionalmente.

Um DLR comunica um estado dentro do sistema que o emite e transmite; por si só, não equivale necessariamente a uma confirmação independente de receção no telemóvel. Nas evidências da regressão, identifica claramente o que observaste: resposta da API, resposta SMPP, callback ou verificação independente do terminal, se esta existir.

• Confirma que cada evento é correlacionado com a referência correta de acordo com o contrato.
• Regista a origem e o momento de observação de cada estado.
• Distingue os estados comunicados pela rota da receção verificada de forma independente.

Comparar antes e depois com critérios e evidências

Executa o mesmo conjunto de casos na versão anterior e na nova, em condições comparáveis. Compara os resultados por interface e cenário, não apenas a percentagem global de testes aprovados. Uma diferença pode ser esperada se o contrato tiver sido alterado deliberadamente; nesse caso, deve estar documentada, aprovada e refletida nos testes antes da implantação.

Guarda a versão da aplicação e do conector, a configuração relevante não secreta, o caso executado, a resposta observada e o resultado esperado. Armazena os dados sensíveis de acordo com as políticas aplicáveis e evita incluir credenciais ou informações pessoais desnecessárias em registos partilhados.

Define os critérios de aprovação antes da execução. No mínimo, os casos obrigatórios do contrato devem produzir o resultado esperado e as diferenças não explicadas devem ser investigadas. Não estabeleças limites de latência, disponibilidade ou entrega sem uma especificação aplicável e uma medição adequada.

• Classifica cada diferença como alteração prevista, regressão confirmada ou resultado ainda não explicado.
• Compara os códigos e os corpos HTTP segundo a API; compara as respostas SMPP segundo a versão e a implementação acordadas.
• Anexa evidências suficientes para repetir o caso sem expor segredos.

Implantação gradual e reversão sem misturar testes com produção

Testa primeiro num ambiente e com destinos autorizados para ensaios, sempre que estejam disponíveis e documentados. Mantém as credenciais, a configuração e as evidências de teste separadas das de produção. Se não existir um ambiente de teste adequado, limita qualquer validação ao que foi aprovado para produção e às regras de consentimento e conformidade aplicáveis.

Antes da implantação, acorda quem decide se a alteração avança ou é interrompida, que casos têm de ser aprovados e que sinais exigem investigação ou reversão. A reversão deve corresponder a um procedimento testado para a aplicação e o conector; não é possível estabelecer uma regra universal de infraestrutura sem conhecer o sistema.

Durante qualquer implantação gradual, identifica claramente que versão gera cada pedido e conserva observabilidade suficiente para distinguir erros de integração dos resultados posteriores da entrega. Não interpretes uma resposta técnica satisfatória como prova da qualidade da rota.

• Confirma que existe uma versão ou configuração anterior recuperável e que o procedimento de reversão foi validado.
• Define os responsáveis, os critérios de interrupção e as evidências mínimas antes de iniciar a alteração.
• Mantém o tráfego de teste identificado e separado do tráfego de produção.

Lista de verificação para manter a compatibilidade

Uma integração mantém-se compatível quando as suas regras podem ser consultadas, os seus testes podem ser repetidos e as alterações intencionais se distinguem das regressões. Revê o contrato quando mudar uma versão da API, uma especificação SMPP, um conector ou uma configuração que afete campos, respostas ou estados. A referência deve ser sempre a documentação atual da interface concreta.

Utiliza esta lista antes de aprovar uma alteração:

• A versão e a interface HTTP ou SMPP sob teste estão documentadas?
• Cada campo, codificação, remetente e identificador tem uma regra sustentada por documentação?
• Existem casos separados para aceitação, rejeição, timeout, desconexão e recuperação?
• Os callbacks e estados são correlacionados de acordo com o contrato e está identificado quem os comunica?
• As evidências distinguem a aceitação técnica, o DLR e a receção verificada no terminal?
• As diferenças em relação à versão anterior estão explicadas e aprovadas?
• Estão definidos os responsáveis, os critérios de interrupção e o procedimento de reversão?
• Os testes e o tráfego de produção estão separados e cumprem as regras aplicáveis?