Quais dados uma API de rastreamento deve retornar? 12 campos além do status atual?
Uma API de rastreamento deve retornar mais do que um rótulo como “Em trânsito”. Além do status atual, procure identificadores da remessa, identidade da transportadora, informações detalhadas sobre o status, mensagens originais da transportadora, histórico de eventos, registros de data e hora dos eventos, localizações, estimativas de entrega, exceções, transferências entre transportadoras, detalhes da entrega e metadados sobre a atualidade dos dados. Juntos, esses 12 grupos de dados ajudam os desenvolvedores a criar fluxos de trabalho confiáveis e fornecem às equipes de operações contexto suficiente para agir.

Este é um contrato de resposta recomendado para desenvolvedores, compradores técnicos e equipes de operações de comércio eletrônico — não uma afirmação de que toda transportadora ou API forneça todos os campos. Alguns valores legitimamente não estarão disponíveis. Um design melhor torna essas lacunas explícitas, em vez de preenchê-las com suposições.
O que torna os dados de rastreamento úteis?
Um status atual responde a uma pergunta específica: qual é o estado resumido da remessa? Ele não explica necessariamente o que aconteceu, quando aconteceu, se as informações são recentes ou o que alguém deve fazer em seguida.
Por exemplo, duas remessas podem exibir “Em trânsito” e ainda assim exigir respostas diferentes. Uma pode ter uma leitura recente em uma unidade e nenhum problema relatado. Outra pode ter um problema de endereço não resolvido registrado no histórico de eventos. Um aplicativo que lê apenas o status principal pode não perceber essa diferença.
Avalie a resposta em relação a três tarefas práticas: associar a remessa ao pedido correto, explicar seu progresso com precisão e decidir se uma ação é justificável. Os campos a seguir dão suporte a essas tarefas. Os nomes dos campos são ilustrativos; não constituem um padrão universal nem o esquema de um provedor específico.
12 campos a avaliar além do status atual
1. Identificadores da remessa e do rastreamento
A resposta deve identificar a remessa descrita. Valores úteis incluem o número de rastreamento enviado, o identificador do registro de rastreamento da API e uma referência do cliente que seu sistema possa associar a um registro de atendimento ou pacote.
Não presuma que um pedido corresponde a uma única remessa. Um pedido pode ser dividido entre vários pacotes, e uma substituição pode criar outra remessa. Armazene os registros de rastreamento no nível do pacote ou do atendimento e depois associe-os ao pedido. Preserve os números de rastreamento como strings para que a formatação e os zeros à esquerda não sejam perdidos.
2. Identidade da transportadora
Procure um identificador estável da transportadora junto a um nome legível. Quando disponível, a resposta deve distinguir uma transportadora fornecida explicitamente pelo seu aplicativo de uma selecionada por detecção automática.
O contexto da transportadora é importante ao interpretar um número de rastreamento e seus eventos. Se a detecção for ambígua, sua integração deve ter uma forma de resolver a situação, em vez de apresentar silenciosamente uma correspondência incerta como confirmada. Mantenha as informações sobre o nível do serviço separadas: o nome da transportadora, por si só, não indica se a remessa usa um serviço expresso, postal ou outro.
3. Detalhes do status normalizado
Junto ao status principal, solicite um código de detalhe ou substatus documentado. Uma categoria ampla pode descrever uma remessa como uma exceção, enquanto o detalhe identifica uma tentativa de entrega, um problema de endereço ou uma retenção relacionada à alfândega.
Use códigos estáveis para a lógica de negócios e rótulos legíveis para a apresentação. Confirme como o provedor mapeia os eventos da transportadora para esses códigos, inclusive como trata eventos desconhecidos ou não mapeados. Um rótulo normalizado facilita o consumo de diferentes fontes de transportadoras, mas não deve apagar distinções necessárias à sua equipe de suporte.
4. Mensagens e códigos originais da transportadora
Conserve a descrição original do evento e o código do evento da transportadora quando fornecidos. Esses valores oferecem aos agentes de suporte um contexto que pode estar ausente em um status normalizado, especialmente quando uma transportadora usa uma expressão operacional específica.
Mantenha o texto original separado das descrições traduzidas ou reescritas. Caso contrário, uma explicação voltada ao cliente pode ser confundida com as palavras exatas da transportadora. Trate o texto da transportadora como entrada não confiável ao exibi-lo: faça o escape adequado e não o renderize como HTML executável.
5. Histórico de eventos de rastreamento
Uma resposta útil deve expor a linha do tempo da remessa, não apenas seu evento mais recente. Idealmente, cada evento deve incluir um identificador, status ou código, descrição, registro de data e hora e informações de localização disponíveis.
Verifique se a API retorna o histórico completo, uma janela limitada ou resultados paginados. Estabeleça também como correções e observações duplicadas são representadas. Seu aplicativo não deve presumir que o primeiro item é sempre o mais recente, a menos que o contrato de resposta garanta explicitamente essa ordenação.
6. Registros de data e hora dos eventos e informações de fuso horário
O horário em que um evento ocorreu é diferente do horário em que a API o recebeu ou retornou. Preserve ambos quando disponíveis. Essa distinção ajuda a explicar por que uma atualização recém-recebida pode descrever algo que aconteceu anteriormente.
Solicite registros de data e hora com deslocamentos UTC explícitos ou notação UTC. A RFC 3339 define um formato adequado para protocolos da Internet, incluindo deslocamentos numéricos de horário. Se uma fonte fornecer apenas o horário local sem um deslocamento conhecido, preserve essa incerteza em vez de tratá-lo silenciosamente como UTC. Nunca sugira precisão de segundos quando a fonte subjacente fornece apenas uma data.
7. Localizações dos eventos e geografia da remessa
Procure componentes estruturados de localização, como cidade, região, país e código postal, quando fornecidos. Preserve também uma string de localização bruta se a conversão para campos estruturados puder causar perda de significado.
O local de uma leitura não é necessariamente a posição atual do pacote. Da mesma forma, a última unidade informada não prova que a encomenda ainda esteja lá. As páginas voltadas ao cliente devem descrevê-la como a localização informada mais recentemente. Evite inferir coordenadas ou um endereço exato de entrega a partir de um texto de leitura incompleto.
8. Data ou janela estimada de entrega
Um campo de entrega estimada deve indicar se contém uma data única ou uma janela, quem o produziu e quando foi atualizado pela última vez. Uma estimativa fornecida pela transportadora e uma previsão calculada separadamente devem permanecer distinguíveis.
Não converta uma estimativa que contenha apenas uma data em um horário preciso de chegada. Sua integração também deve lidar com estimativas revisadas ou retiradas sem manter uma promessa desatualizada na página de rastreamento. Se não existir uma estimativa, mostre que ela não está disponível em vez de calculá-la com base em uma suposição sem suporte.
9. Motivo da exceção e ação necessária
As informações da exceção devem explicar o problema e, quando a fonte permitir, identificar uma ação, a parte responsável ou um prazo. Um aviso geral de atraso é operacionalmente diferente de uma solicitação de informações do destinatário.
Mantenha os fatos relatados separados das decisões do seu próprio fluxo de trabalho. Por exemplo, sua empresa pode abrir uma tarefa de suporte após um período configurado sem atualizações. Essa é uma regra interna de escalonamento, não uma evidência de que a transportadora declarou a encomenda perdida. Não gere instruções de pagamento nem solicitações de informações confidenciais a partir de textos de rastreamento ambíguos.
10. Transferências entre transportadoras e números de rastreamento relacionados
Quando uma remessa passa entre operadores, os dados úteis incluem a próxima transportadora, um número de rastreamento associado e a relação entre os registros original e posterior. Isso pode ajudar a preservar a continuidade quando a etapa de entrega usa um identificador diferente.
Trate uma transferência relatada como uma relação, em vez de substituir a transportadora original. Não mescle registros apenas porque seus destinos ou números de rastreamento parecem semelhantes. Se a relação não for fornecida ou confirmada de outra forma, mantenha-a não resolvida em vez de inventar uma jornada contínua.
11. Resultado da entrega e referências de comprovante
Quando uma entrega for informada, a resposta deve fornecer o horário de entrega registrado e qualquer detalhe disponível, como uma descrição do local seguro ou a categoria do destinatário. Uma referência de comprovante de entrega também pode ser útil quando a transportadora e o serviço a disponibilizarem.
Um status de entregue não deve ser tratado como prova de que o destinatário pretendido aceitou pessoalmente a encomenda. Assinaturas, fotografias, nomes e localizações precisas podem conter informações pessoais. Limite o acesso, evite expor esses detalhes em páginas públicas de rastreamento e confirme quaisquer requisitos de autorização ou validade dos links de comprovantes.
12. Atualidade, estado da consulta e metadados da resposta
Solicite metadados suficientes para distinguir o evento mais recente da remessa da recuperação de dados bem-sucedida mais recente. Valores úteis incluem a última verificação bem-sucedida, a última tentativa malsucedida, o horário de geração da resposta e se os dados retornados estão em cache ou são parciais.
Uma solicitação bem-sucedida à API não estabelece, por si só, que a transportadora publicou uma nova leitura. A semântica da resposta HTTP descreve o resultado da solicitação; o progresso da remessa pertence aos dados do aplicativo. Preserve os erros de recuperação separadamente das exceções da remessa para que um problema temporário de conexão não se transforme em um falso alerta de entrega.
Os dados ausentes precisam de um significado definido
A presença do campo é apenas parte do contrato. Sua equipe também precisa entender o que significa um valor ausente. Uma estimativa de entrega pode não estar disponível na fonte, ainda não ter sido recuperada ou não ser aplicável após a entrega. Essas situações não devem gerar automaticamente a mesma mensagem ao cliente.
- Desconhecido: O valor ainda não foi estabelecido.
- Não fornecido: A fonte não forneceu o valor nos dados recuperados.
- Não aplicável: O campo não se aplica a este registro ou estado.
- Falha na recuperação: O sistema não conseguiu concluir a consulta relevante.
Estas são distinções recomendadas, não valores literais obrigatórios. Seja qual for a representação escolhida, documente-a. Evite datas de preenchimento, objetos vazios que se pareçam com registros válidos e coordenadas padrão que possam ser confundidas com localizações reais.
Como testar a resposta antes da integração
Avalie cargas reais das transportadoras, serviços e rotas de envio utilizados pela sua empresa. Um esquema pode listar um campo opcional sem garantir que todas as fontes subjacentes o preencham. Para uma integração com a 17TRACK, use a documentação oficial da Tracking API para verificar o contrato de resposta, em vez de tratar os nomes conceituais dos campos deste guia como parâmetros prontos para copiar.
- Crie uma amostra representativa. Inclua remessas recém-registradas, remessas ativas, tentativas de entrega, entregas concluídas e casos disponíveis de transferência.
- Rastreie os campos até os eventos. Confirme que o status exibido, o evento mais recente e os detalhes da entrega descrevem um registro consistente. Investigue as discrepâncias em vez de ocultá-las.
- Teste atualizações atrasadas e repetidas. Reprocesse a mesma carga e receba um evento mais antigo depois de um mais recente. Confirme que nenhum dos casos cria notificações duplicadas nem reverte incorretamente o estado exibido.
- Teste valores ausentes e malformados. Inclua estimativas ausentes, localizações desconhecidas, códigos de status não familiares e registros de data e hora incompletos. O aplicativo deve continuar utilizável sem inventar substitutos.
- Separe falhas de transporte dos resultados do rastreamento. Uma falha de autenticação, um tempo limite ou uma resposta malformada deve seguir um fluxo de erro de integração, não um fluxo de exceção da remessa.
- Valide a visualização do cliente. Verifique se referências internas, detalhes brutos de diagnóstico e informações pessoais não vazam para páginas ou notificações públicas.
Para atualizações baseadas em webhooks, verifique também os identificadores de entrega, a autenticação, o comportamento de novas tentativas e o tratamento de reexecuções na documentação do provedor. Esses são requisitos de integração, não fatos da remessa. Seu receptor deve processar entregas repetidas com segurança e não deve presumir que a ordem de chegada seja igual à ordem dos eventos.
O critério de aceitação deve ser prático: seu aplicativo consegue explicar a remessa sem fazer afirmações sem suporte e sua equipe de operações consegue identificar a próxima ação justificável? Uma carga menor e bem definida pode ser mais útil do que uma resposta maior cheia de valores opcionais não explicados.
FAQ
Toda remessa precisa ter todos os 12 grupos de dados preenchidos?
Não. Evidências de entrega, números de rastreamento posteriores e datas estimadas de entrega podem não estar disponíveis ou não ser aplicáveis. Exija definições claras dos campos e um comportamento previsível para valores ausentes, em vez de exigir o preenchimento universal. Verifique os campos mais importantes em relação à sua combinação real de envios.
Devemos armazenar a resposta bruta ou apenas os campos normalizados?
Armazene campos normalizados para a lógica do aplicativo. Manter cargas relevantes da fonte também pode ajudar na depuração e nas alterações de mapeamento, sujeito aos seus requisitos de privacidade, segurança, contratuais e de retenção. Restrinja o acesso e evite manter conteúdo sensível simplesmente porque ele aparece em uma resposta.
Qual registro de data e hora deve determinar o evento mais recente?
Use a cronologia documentada dos eventos e as regras de ordenação do provedor, considerando fusos horários e correções. O horário de recebimento informa quando seu sistema tomou conhecimento de um evento, não necessariamente quando ele ocorreu. Se os registros de data e hora estiverem incompletos ou conflitantes, preserve a ambiguidade em vez de afirmar uma sequência precisa.
Uma API de rastreamento pode confirmar que um pacote foi perdido?
Considere uma perda como informada pela transportadora somente quando a fonte permitir explicitamente essa interpretação. Um longo período sem leituras pode justificar uma investigação de acordo com suas regras operacionais, mas o silêncio, por si só, não estabelece uma perda. Mantenha “rastreamento desatualizado” e “perdido conforme informado” como conceitos separados.
Um status de entregue é suficiente para encerrar uma reclamação do cliente?
Não automaticamente. Ele estabelece o resultado informado do rastreamento, mas pode não resolver a contestação do destinatário. Analise os detalhes disponíveis da entrega, a conta do cliente e seu processo de suporte. Evite tratar um rótulo de status como substituto da investigação de informações conflitantes.
Fontes
- Documentação da Tracking API da 17TRACK — a referência específica do produto para verificar os campos e o comportamento documentados de uma integração; os 12 grupos acima são recomendações editoriais, não uma reprodução de seu esquema.
- RFC 3339: Data e hora na Internet: registros de data e hora — representação de registros de data e hora e convenções de deslocamento de horário.
- RFC 9110: Semântica HTTP — semântica das respostas HTTP, distinta do status comercial no nível da remessa.


