Skip to main content
HomeBlogGuiasComo validar números de rastreamento antes do envio à API: 7 regras a seguir

Como validar números de rastreamento antes do envio à API: 7 regras a seguir

17TRACK

Valide um número de rastreamento em camadas antes de enviá-lo a uma API de rastreamento: normalize a entrada, verifique sua estrutura básica, confirme o contexto da transportadora, aplique um checksum somente quando a transportadora documentar um e rejeite valores claramente inseguros ou incompletos. Não dependa de uma única expressão regular universal. Os formatos dos números de rastreamento diferem por transportadora, serviço, país e tipo de envio; portanto, um validador eficaz deve impedir solicitações inválidas sem bloquear números legítimos que usem um formato desconhecido.

Como validar números de rastreamento antes do envio à API: 7 regras

Este guia foi escrito para desenvolvedores e equipes de operações que integram o rastreamento de remessas a um sistema de gerenciamento de pedidos, fluxo de trabalho de armazém, portal do cliente ou aplicação de comércio eletrônico. O objetivo não é provar que uma encomenda existe antes do envio. A validação sintática e a validação do status da remessa são etapas distintas.

O que a validação pode — e não pode — confirmar

Um validador anterior ao envio pode identificar problemas comuns de entrada, como um valor vazio, espaços acidentais, caracteres não suportados, comprimento excessivo ou um número de rastreamento colocado no campo errado. Ele também pode identificar uma provável transportadora quando ela é conhecida e o formato está documentado.

Normalmente, ele não pode confirmar que um número pertence a uma remessa real, que a encomenda foi aceita por uma transportadora ou que o número pode ser rastreado no momento. Essas questões exigem uma consulta à transportadora ou à plataforma de rastreamento. Um número pode passar por uma verificação de formato e ainda assim não ter sido utilizado, conter um erro sutil de digitação, estar expirado ou estar associado a um serviço diferente.

As sete regras

1. Normalize o valor sem alterar seu significado

Usuários e sistemas de origem frequentemente adicionam espaços no início ou no fim, quebras de linha, espaços inseparáveis ou caracteres de formatação. Normalize esses elementos com segurança antes da validação. Uma primeira etapa comum é remover os espaços em branco ao redor e converter espaços não imprimíveis em espaços comuns. Se o formato documentado pela transportadora permitir espaços internos ou hífens, decida se deve removê-los para a solicitação à API ou preservar o valor original para exibição e auditoria.

Mantenha dois valores sempre que possível: a entrada original e um valor canônico. O original ajuda as equipes de suporte a investigar problemas de qualidade de dados; o valor canônico é usado para validação e envio. Evite transformações que possam alterar os identificadores. Não converta automaticamente letras em números, substitua caracteres ambíguos ou remova toda a pontuação, a menos que a documentação da transportadora ou da API relevante permita explicitamente esse comportamento.

O tratamento de Unicode merece atenção. Um caractere visualmente semelhante de outro alfabeto pode não ser aceito por uma API, mesmo que pareça uma letra ou dígito ASCII. Restringir o valor canônico ao conjunto de caracteres permitido pela integração selecionada pode evitar erros posteriores confusos.

2. Rejeite valores que não passem pelas verificações estruturais básicas

Antes de aplicar uma lógica específica da transportadora, verifique se o valor está presente e é plausível. Verificações úteis incluem comprimento mínimo e máximo, classes de caracteres permitidas e se o valor contém apenas espaços em branco ou um marcador como “N/A”, “TBD” ou “test”. Os limites exatos devem vir do contrato da API ou da documentação da transportadora. Evite inventar um máximo universal apenas porque a maioria dos exemplos é curta.

Uma verificação estrutural deve ser deliberadamente conservadora. Por exemplo, uma regra que permite apenas dígitos rejeitará identificadores alfanuméricos válidos. Uma regra que exige um comprimento fixo pode rejeitar variantes de serviço ou formatos internacionais. Use verificações genéricas para detectar erros óbvios e aplique verificações mais específicas somente quando a transportadora e o serviço forem conhecidos.

Valide também o tipo de dados na fronteira da aplicação. Um número de rastreamento normalmente deve ser tratado como uma string, não como um número inteiro. A conversão numérica pode remover zeros à esquerda e criar problemas de precisão em sistemas que utilizam tipos numéricos de largura fixa. Preserve o valor exatamente como uma string após a normalização aprovada.

3. Use o contexto da transportadora em vez de adivinhar apenas pelo número

Um número de rastreamento sem transportadora é uma entrada ambígua. Diferentes transportadoras podem usar comprimentos, prefixos ou conjuntos de caracteres sobrepostos, e um formato plausível para uma transportadora pode ser inválido para outra. Se o pedido, a etiqueta, o sistema do armazém ou a conta do comerciante já identificar a transportadora, envie esse contexto junto com o número de rastreamento sempre que a API permitir.

O contexto da transportadora melhora tanto a validação quanto o roteamento. Ele permite que a aplicação selecione as regras de formato relevantes, reduz falsos correspondências e torna as mensagens de erro mais úteis. Também impede que um resultado de detecção automática seja tratado como fato quando várias transportadoras poderiam aceitar um valor semelhante.

Se a transportadora for desconhecida, use uma abordagem em duas etapas. Primeiro, execute verificações genéricas de segurança. Em seguida, envie o valor somente por meio de um fluxo de API que ofereça explicitamente a detecção da transportadora, ou coloque-o em uma fila de revisão quando o processo empresarial exigir uma transportadora confirmada. Não atribua silenciosamente uma transportadora com base apenas em um prefixo, a menos que esse mapeamento seja mantido e documentado.

4. Aplique checksums somente quando a regra estiver documentada

Alguns sistemas de identificação usam dígitos de verificação, mas os números de rastreamento não são regidos por um único padrão universal de checksum. Um checksum pode detectar certos erros de transcrição, mas não prova que uma remessa existe. Mais importante ainda, aplicar o algoritmo de checksum errado pode rejeitar números válidos.

Implemente um checksum somente quando a transportadora, o serviço, a especificação da etiqueta ou a documentação da API relevante definir o algoritmo e a parte da entrada abrangida por ele. Registre a versão da regra e teste-a com exemplos oficiais. Se não houver uma regra autorizada, ignore o checksum em vez de adivinhar com base em padrões observados em uma pequena amostra.

Trate o resultado de um checksum como um sinal, não como uma decisão completa de validação. Uma verificação malsucedida pode justificar o bloqueio de um envio quando a regra for oficial. Uma verificação bem-sucedida deve levar o valor à próxima etapa, não marcá-lo como uma remessa ativa.

5. Separe a validação do formato da elegibilidade da API

Um valor pode estar bem formado e ainda assim ser inadequado para o endpoint chamado. Antes do envio, consulte a documentação da API sobre campos obrigatórios, identificadores de transportadoras aceitos, requisitos de autenticação, limites de solicitações, comportamento para duplicatas e quaisquer restrições sobre tipos de serviço ou destinos. Essas são regras de integração, não regras do número de rastreamento, mas determinam se um identificador válido poderá ser processado com sucesso.

A documentação da API de Rastreamento da 17TRACK é um exemplo de por que essa distinção é importante: os desenvolvedores precisam seguir o modelo de solicitação da plataforma e o comportamento de integração compatível, em vez de inventar uma solicitação com base na aparência de um número de rastreamento. Consulte a documentação atual sobre requisitos de endpoint e tratamento de respostas em documentação da API da 17TRACK.

Mantenha os erros de validação separados dos erros de transporte e autenticação. “Formato de número de rastreamento inválido”, “transportadora desconhecida”, “limite de solicitações atingido” e “autorização falhou” exigem ações diferentes. Uma única mensagem genérica de “falha no envio” torna as novas tentativas e os relatórios operacionais menos confiáveis.

6. Proteja a API com entradas limitadas, deduplicação e novas tentativas seguras

A validação também é uma proteção operacional. Aplique um comprimento máximo à entrada antes de analisá-la ou registrá-la. Rejeite caracteres de controle e estruturas de payload inesperadas. Aplique limites de solicitações na fronteira da sua própria aplicação para que uma importação com falha não gere um volume descontrolado de solicitações.

Faça a deduplicação antes do envio quando o processo empresarial não exigir registros repetidos. Uma chave de deduplicação útil pode incluir o número de rastreamento canônico, a transportadora, a conta e o contexto da remessa. A chave correta depende do seu fluxo de trabalho; o mesmo identificador às vezes pode ser reutilizado em diferentes serviços ou registros empresariais, portanto não presuma que o número sozinho seja sempre globalmente exclusivo.

Use novas tentativas limitadas com espera progressiva para falhas temporárias e evite repetir erros permanentes de validação. Armazene um registro de idempotência ou de envio quando a API e sua arquitetura oferecerem suporte. Registre informações suficientes para solucionar problemas da solicitação, mas proteja credenciais, dados dos clientes e detalhes confidenciais das remessas. Um validador deve reduzir falhas repetidas, não criar um segundo problema de segurança por meio de registros excessivos.

7. Confirme o resultado após o envio e monitore falsos positivos

A regra final é tratar a validação anterior ao envio como uma barreira, não como um veredito. Depois que a solicitação for aceita, examine a resposta da API e armazene seu status, identificador da solicitação, associação da transportadora e qualquer código de erro documentado. Se a plataforma aceitar a solicitação, mas ainda não puder retornar eventos de movimentação, isso pode indicar um atraso no processamento, e não um número inválido.

Defina uma política de acompanhamento para números que permaneçam sem resolução. A janela de tempo deve refletir a transportadora, o serviço, a origem da remessa e sua política de atendimento ao cliente; não existe um período universal que prove que um número é inválido. Encaminhe registros com transportadora ausente, erros repetidos do provedor, resultados conflitantes de transportadoras ou um status que não corresponda ao registro do pedido.

Meça rejeições e aceitações incorretas. Uma expressão regular rigorosa pode reduzir envios malformados e, ao mesmo tempo, bloquear indevidamente remessas legítimas. Um validador permissivo pode aumentar as solicitações aceitas, mas gerar ruído posteriormente. Revise amostras com falha por transportadora e serviço, atualize as regras documentadas por meio do controle de versões e teste as alterações com um conjunto representativo de dados de teste que preserve a privacidade.

Uma sequência prática de validação

Uma implementação sustentável pode usar a seguinte sequência:

  1. Verifique se a solicitação contém um valor string e um registro empresarial válido.
  2. Salve a entrada original e crie uma forma canônica documentada.
  3. Rejeite valores vazios, marcadores, caracteres inseguros e valores fora do intervalo de comprimento documentado.
  4. Resolva a transportadora a partir de dados confiáveis do pedido ou use um fluxo de detecção explicitamente compatível.
  5. Aplique regras de sintaxe e checksum específicas da transportadora somente quando houver documentação oficial que as apoie.
  6. Verifique os requisitos do endpoint, o estado de duplicidade e a elegibilidade para novas tentativas.
  7. Envie, classifique a resposta, armazene o resultado e agende o acompanhamento dos registros não resolvidos.

Essa sequência facilita o teste do validador porque cada decisão tem uma justificativa diferente. Ela também fornece às equipes de operações categorias de falha acionáveis, em vez de um único erro opaco.

Checklist de implementação

  • Armazene números de rastreamento como strings para preservar os zeros à esquerda.
  • Mantenha os valores original e canônico separadamente quando a auditabilidade for importante.
  • Mantenha as regras das transportadoras como configurações versionadas, não como condições codificadas espalhadas.
  • Teste letras, dígitos, hífens, espaços em branco, caracteres Unicode semelhantes, marcadores e comprimentos-limite.
  • Use o contexto confiável da transportadora sempre que estiver disponível.
  • Não deduza a existência de uma remessa a partir de uma correspondência bem-sucedida com uma expressão regular.
  • Classifique os erros permanentes de validação separadamente dos erros temporários da API ou da rede.
  • Consulte a documentação do provedor antes de alterar regras de formato ou a lógica das solicitações.

Perguntas frequentes

Uma expressão regular pode validar um número de rastreamento?

Ela pode validar um padrão limitado quando o formato da transportadora e do serviço é conhecido. Não pode provar que o número existe, pertence a uma remessa específica ou está ativo no momento. Uma expressão universal provavelmente criará rejeições ou correspondências incorretas.

Um número que parece inválido deve ser enviado à API?

Valores claramente vazios, inseguros ou estruturalmente impossíveis normalmente devem ser interrompidos antes do envio. Um formato desconhecido, mas que seja seguro, não deve ser rejeitado apenas porque não corresponde a uma suposição interna. Consulte a documentação da transportadora ou use primeiro um processo de detecção compatível.

Um checksum é suficiente para confirmar uma remessa?

Não. Um checksum, quando aplicável, apenas testa se o valor satisfaz uma regra matemática. Ele não confirma que uma transportadora emitiu o número ou que a encomenda entrou na rede.

O que deve acontecer quando a transportadora é desconhecida?

Execute verificações genéricas de segurança e use um fluxo de API que ofereça explicitamente a detecção da transportadora, se disponível. Caso contrário, mantenha o registro para enriquecimento ou revisão manual em vez de adivinhar silenciosamente uma transportadora.

Como os erros da API devem ser tratados?

Classifique-os por causa. Corrija entradas malformadas e valores de transportadoras não suportadas; repita falhas temporárias de rede ou do provedor com limites e espera progressiva; e encaminhe erros de autenticação ou cota ao responsável pela integração. Armazene os detalhes da resposta necessários para o diagnóstico sem expor segredos.

Fontes