Validação de arquivos de envio em massa de SMS A2P: guia operacional

Quais problemas a validação prévia à criação de mensagens evita

Um envio em massa pode reunir dados corretos, registros incompletos e erros que impedem a interpretação de uma linha. Validar antes de criar as mensagens permite detectar esses problemas em uma etapa controlada e indicar quais registros precisam ser revisados, em vez de descobri-los depois que o processamento já começou.

A validação deve ser entendida como um controle de dados e de regras previamente definidas. Ela não comprova que existe consentimento para entrar em contato, que um remetente está autorizado em determinado destino ou que uma mensagem será entregue. Essas verificações pertencem a processos distintos e dependem do contexto, das regras aplicáveis e dos recursos disponíveis.

• Defina qual estrutura o sistema aceita e o que significa cada campo.
• Separe erros de leitura de descumprimentos de regras operacionais.
• Mantenha uma referência inequívoca entre cada registro original e o respectivo resultado.

Defina o contrato de dados

Antes de aceitar arquivos, documente um contrato de dados: formatos aceitos, codificação esperada, cabeçalhos reconhecidos, campos obrigatórios e tratamento de valores vazios. Se forem aceitas variantes, especifique-as explicitamente. Não dependa de suposições, como a ordem das colunas ou a interpretação automática de datas e números.

Ao ler o arquivo, verifique se ele pode ser interpretado no formato declarado e se as colunas obrigatórias estão presentes. Diferencie um arquivo que não pode ser analisado de outro que pode ser lido, mas contém linhas incompletas. A primeira situação afeta o arquivo inteiro; a segunda geralmente pode ser informada por registro.

As evidências disponíveis não indicam uma convenção única para codificação, cabeçalhos ou campos obrigatórios aplicável a todos os envios em massa de SMS A2P. Por isso, essas regras devem ser definidas para cada integração e comunicadas a quem prepara os arquivos.

• Publique um modelo e uma definição para cada coluna, incluindo formatos e valores permitidos.
• Informe se colunas adicionais, campos vazios ou cabeçalhos alternativos são aceitos.
• Use erros distintos para arquivo ilegível, cabeçalho ausente e dado obrigatório vazio.

Validações por registro: número, remetente e conteúdo

Para cada linha, valide se o número do destinatário está presente e pode ser interpretado de acordo com as regras definidas para a integração. Se houver normalização, defina e documente seu comportamento; não acrescente prefixos, remova caracteres nem altere a interpretação com base em suposições. A recomendação E.164 é uma referência para numeração internacional, mas as informações disponíveis aqui não permitem detalhar suas regras nem concluir que uma sequência que as cumpra possa ser roteada.

Verifique se o remetente e o conteúdo estão presentes quando o caso de uso exigir e se podem ser representados no formato esperado. Uma sintaxe válida do remetente não comprova que ele esteja autorizado para o destino. Da mesma forma, o fato de o texto ser legível não confirma que ele cumpre as regras de consentimento, as políticas aplicáveis ou as restrições de uma rota.

Mantenha separadas as verificações de dados e as decisões de envio. Uma linha pode ser sintaticamente válida e, ainda assim, exigir uma análise de autorização, política ou elegibilidade antes de ser processada.

• Defina os formatos de número aceitos e os casos que são rejeitados ou precisam de análise.
• Valide o remetente conforme as regras configuradas para o contexto, sem tratar a validação sintática como autorização.
• Verifique se o conteúdo pode ser interpretado e se os campos de personalização obrigatórios estão disponíveis.

Detecte duplicados sem alterar a intenção

Duas linhas semelhantes não são necessariamente duplicadas: podem representar envios legítimos para a mesma pessoa, por exemplo, em momentos distintos ou com objetivos diferentes. Antes de sinalizar duplicados, defina qual combinação de campos e qual período, se aplicável, serão usados para detectar correspondências. Não exclua nem combine registros automaticamente sem uma regra acordada com a pessoa responsável pelo processo.

Convém distinguir entre duplicidade exata no arquivo, correspondência segundo uma regra de negócio e repetição legítima. A decisão pode ser alertar, bloquear ou permitir o registro; ela deve ser explícita, auditável e coerente com a finalidade do envio.

• Defina a chave de comparação e o escopo da detecção antes de implementá-la.
• Preserve os registros originais e informe quais linhas correspondem entre si.
• Não apresente uma correspondência como prova de erro ou fraude.

Classifique os erros por etapa

Uma classificação útil separa pelo menos três níveis. Erros de formato impedem a leitura do arquivo ou a interpretação de um campo. Erros de regras de negócio indicam que um valor não atende a uma condição acordada. Restrições de envio abrangem decisões posteriores sobre autorização, políticas ou possibilidade de processar o tráfego. Não misture essas categorias em um único estado genérico de “inválido”.

Um erro corrigível pode ser resolvido alterando o arquivo ou o dado e fazendo uma nova validação. Uma rejeição definitiva, dentro das regras configuradas, indica que o registro não deve avançar naquele processo. Evite classificar um erro como definitivo quando ele apenas indica falta de informação ou necessidade de análise. A classificação deve refletir a causa conhecida, não uma conclusão que o controle não pode comprovar.

• Use estados distintos para arquivo ilegível, dado corrigível, regra não cumprida e análise pendente.
• Explique que ação a pessoa responsável pelo preparo do envio pode tomar.
• Não transforme uma falha de validação em uma afirmação sobre consentimento, identidade ou entrega.

Resultados úteis e referência à linha

Cada resultado da validação deve indicar qual registro foi avaliado e a causa do aviso ou da rejeição. Para isso, mantenha uma referência estável ao registro de origem, como o número da linha no arquivo recebido e, se houver, um identificador próprio do envio. A referência deve permanecer válida mesmo que o sistema transforme ou normalize valores para processá-los.

Descreva o campo afetado, a regra aplicada e uma ação possível. Evite mensagens ambíguas como “erro no número” quando for possível indicar que o destinatário está ausente ou que o valor não corresponde ao formato esperado. As informações retornadas devem ser suficientes para permitir a correção, sem expor dados pessoais desnecessários.

• Inclua o identificador do envio, a referência da linha, o campo, o resultado e um motivo compreensível.
• Diferencie avisos de rejeições e explique o que fazer em seguida.
• Proteja os dados pessoais em relatórios, registros e canais de suporte.

Envios grandes, lotes e reenvios

O tamanho máximo do arquivo, o número de registros por lote e a estratégia de processamento dependem do sistema que recebe o envio. Não há evidências aqui que permitam recomendar limites numéricos universais. Defina os limites com base nos recursos verificados da implementação e divulgue-os antes que as equipes preparem seus arquivos.

Se o processamento ocorrer em lotes, mantenha o identificador do envio e a posição de cada linha em todas as etapas. Planeje os reenvios para que uma falha parcial não transforme silenciosamente uma repetição em novas mensagens. A semântica de tentativas e deduplicação deve ser especificada pela integração; ela não pode ser inferida apenas pelo fato de o arquivo ter sido enviado novamente.

• Documente os limites e comportamentos verificados na integração específica.
• Registre o que foi validado e processado, sem ocultar resultados parciais.
• Defina como uma repetição do envio será reconhecida antes de permitir reenvios.

Rastreabilidade e retenção proporcional

Mantenha uma relação verificável entre o arquivo recebido, cada linha, o resultado da validação e qualquer mensagem que venha a ser criada. Essa rastreabilidade ajuda a investigar erros e a responder a questões operacionais, mas deve se limitar aos dados necessários para a finalidade definida.

Estabeleça uma política de retenção para arquivos e resultados que determine quem pode acessá-los, quais dados serão mantidos e quando serão excluídos. As informações disponíveis não determinam um prazo adequado nem substituem as obrigações aplicáveis em cada jurisdição. Defina esses limites com as pessoas responsáveis por privacidade, segurança e conformidade, e evite manter cópias completas quando uma referência mínima for suficiente.

• Mantenha identificadores de envio e de linha que permitam reconstruir o resultado sem duplicar dados desnecessariamente.
• Restrinja o acesso e evite incluir números ou mensagens completos nos registros quando isso não for necessário.
• Determine os prazos de retenção de acordo com a finalidade e as obrigações aplicáveis.