Como registrar um número de rastreamento via API: campos da solicitação, códigos das transportadoras e respostas
Para registrar um número de rastreamento via API, envie uma solicitação de registro autenticada contendo o número de rastreamento da remessa e, quando necessário, um identificador da transportadora. Em seguida, verifique a resposta de cada remessa enviada — não apenas o status HTTP — e salve se o registro foi bem-sucedido, falhou ou permanece incerto. O registro inicia o fluxo de rastreamento; ele não comprova que a transportadora escaneou o pacote ou que os eventos de rastreamento já estão disponíveis.
Este guia é destinado a desenvolvedores que conectam um sistema de gerenciamento de pedidos, uma aplicação de armazém ou uma plataforma de comércio eletrônico a uma API de rastreamento. Ele usa o 17TRACK como exemplo concreto de integração e explica quais detalhes devem ser verificados na documentação da versão da API selecionada.
O que o registro faz — e o que ele não faz
Uma solicitação de registro informa a um serviço de rastreamento qual remessa você deseja rastrear. Ela é diferente de comprar uma etiqueta de envio, agendar uma coleta ou solicitar que uma transportadora crie uma remessa. Em uma integração típica, o fluxo de envio gera primeiro um número de rastreamento, e sua aplicação registra esse número depois.
Mantenha estes três eventos separados na sua aplicação:
- Remessa criada: seu sistema de envio atribuiu um número de rastreamento.
- Registro aceito: o serviço de rastreamento aceitou a remessa para rastreamento.
- Informações de rastreamento recebidas: os eventos da transportadora ficaram disponíveis por meio do serviço de rastreamento.
Não atualize um pedido para “em trânsito” simplesmente porque o registro foi bem-sucedido. Uma etiqueta recém-criada talvez ainda não tenha um escaneamento físico de aceitação. O status da remessa exibido ao cliente deve vir dos eventos de rastreamento interpretados pelas suas regras de mapeamento de status, não da resposta de registro.
Para integrações com o 17TRACK, comece pela visão geral da Tracking API e use a documentação oficial da API como autoridade para endpoints, definições de campos, autenticação e códigos de resposta. Os exemplos abaixo concentram-se no registro, e não nas tarefas separadas de recuperar resultados ou receber atualizações.
Prepare os campos da solicitação antes de escrever a chamada da API
A preparação mais útil é um pequeno contrato de campos entre seu sistema de envio e sua integração de rastreamento. Decida de onde cada valor se origina, se ele pode estar ausente e como será validado.
| Campo ou valor | Finalidade | Regra de implementação |
|---|---|---|
| Número de rastreamento | Identifica a remessa a ser rastreada. | Armazene e transmita-o como uma string; preserve os zeros à esquerda. |
| Identificador da transportadora | Identifica a transportadora no sistema do provedor de rastreamento. | Use o identificador documentado pelo provedor, não um código interno do armazém. |
| Referência interna | Conecta o registro ao seu registro de remessa. | Use um campo de referência compatível, se disponível; mantenha seu próprio mapeamento no banco de dados de qualquer forma. |
| Dados adicionais de identificação | Podem ajudar a identificar uma remessa quando uma transportadora exige mais do que seu número de rastreamento. | Envie apenas os campos documentados para essa integração e transportadora. |
| Credencial da API | Autentica a conta que faz a chamada. | Mantenha-a no servidor e exclua-a dos logs da aplicação. |
Trate o número de rastreamento como um identificador
Nunca converta um número de rastreamento em um número inteiro. A conversão numérica pode remover zeros à esquerda, e valores grandes podem perder precisão em alguns ambientes de programação. Remova espaços em branco acidentais ao redor, mas não remova pontuação nem altere maiúsculas e minúsculas, a menos que a documentação relevante ou o formato da transportadora aceite essa normalização.
Valide erros óbvios de entrada antes de chamar a API: strings vazias, quebras de linha inesperadas e um número de pedido copiado para o campo de número de rastreamento. Evite impor uma única regra universal de comprimento ou caracteres a todas as transportadoras. Uma regra de validação adequada para uma transportadora pode rejeitar números legítimos de outra.
Mantenha as referências de pedidos separadas das identidades das remessas
Um pedido pode ter vários pacotes, e uma remessa de substituição pode introduzir outro número de rastreamento. Modele o registro no nível da remessa ou do pacote, em vez de presumir um número de rastreamento por pedido.
Se você usar uma tag ou um campo de referência compatível com o provedor, prefira uma referência de remessa opaca em vez do endereço de e-mail ou do endereço residencial do cliente. Seu próprio banco de dados deve continuar sendo a conexão oficial entre pedidos, remessas, números de rastreamento e mapeamentos de transportadoras.
Escolha o código correto da transportadora
Um código de transportadora não é necessariamente um identificador universal do setor. O valor reconhecido por uma plataforma de rastreamento pode ser diferente do nome da transportadora armazenado no seu software de envio. Até mesmo dois sistemas que usam códigos numéricos podem atribuir números diferentes à mesma transportadora.
Mantenha um mapeamento explícito do seu serviço de envio para o identificador da transportadora usado pelo provedor de rastreamento. Quando necessário, diferencie a operação regional ou o serviço de uma transportadora de sua marca mais ampla. Um mapeamento baseado apenas em um nome de exibição pode se tornar ambíguo quando os sistemas de envio usam aliases.
- Quando a transportadora é conhecida: use o identificador documentado da transportadora quando houver suporte, especialmente quando os formatos dos números de rastreamento se sobrepõem.
- Quando a transportadora é desconhecida: use a detecção automática somente pelo mecanismo documentado. Não presuma que omissão, uma string vazia, zero e null significam a mesma coisa.
- Quando o resultado parece incorreto: verifique a etiqueta original, o serviço de envio e o mapeamento antes de registrar repetidamente o mesmo número.
A detecção automática é útil, mas não é prova de que uma transportadora específica esteja fisicamente com a remessa. Da mesma forma, um código de transportadora válido não garante que o número de rastreamento fornecido pertença a essa transportadora.
Mantenha os mapeamentos de transportadoras configuráveis, em vez de espalhá-los pelo código da aplicação. Registre quando um mapeamento foi verificado pela última vez e inclua uma remessa conhecida nos testes de regressão sempre que alterá-lo.
Exemplo: envie uma solicitação de registro ao 17TRACK
O exemplo a seguir ilustra o endpoint de registro do 17TRACK v2.2, o cabeçalho de autenticação 17token e um array contendo um objeto de número de rastreamento. Confirme se esta versão e seus requisitos de solicitação correspondem à sua conta e à documentação oficial antes da implantação. O número de rastreamento é um placeholder e deve ser substituído por um identificador real de remessa.
curl --request POST \
--url 'https://api.17track.net/track/v2.2/register' \
--header "17token: ${TRACKING_API_TOKEN}" \
--header 'Content-Type: application/json' \
--data '[
{
"number": "YOUR_TRACKING_NUMBER"
}
]'
Este exemplo mínimo não demonstra a seleção da transportadora nem campos suplementares específicos da transportadora. Consulte a documentação de registro para determinar como funciona a detecção da transportadora quando o campo da transportadora é omitido e se sua remessa precisa de informações adicionais. Se você fornecer uma transportadora, use o campo carrier documentado e o identificador esperado por essa versão da API.
Execute esta solicitação em um ambiente do lado do servidor. Não incorpore o token em uma loja pública, script de navegador ou aplicação móvel distribuída aos clientes. Uma variável de ambiente é conveniente para um exemplo local; as implantações de produção devem usar os controles de gerenciamento de segredos da sua organização.
Antes de aumentar o volume, teste uma remessa conhecida e examine a resposta completa. Em seguida, teste uma entrada inválida e um lote contendo itens válidos e inválidos. Essas verificações revelam se sua integração realmente trata resultados no nível do item, em vez de apenas reconhecer uma resposta HTTP bem-sucedida.
Leia a resposta em três níveis
Um manipulador de respostas confiável responde a três perguntas distintas: a solicitação chegou ao serviço, o serviço aceitou a operação e o que aconteceu com cada remessa?
1. Resultado HTTP e de transporte
Um tempo limite de conexão, uma falha de TLS ou uma resposta interrompida não informa necessariamente se o servidor processou a solicitação. Marque esse resultado como incerto até conseguir reconciliá-lo. Um status HTTP de sucesso confirma uma troca HTTP bem-sucedida, mas você ainda precisa examinar a resposta da aplicação.
2. Resultado no nível da solicitação
Examine o resultado geral e os campos de erro documentados pela API. Erros de autenticação, JSON malformado e restrições da conta exigem ações diferentes. Armazene o código e a mensagem de erro originais do provedor, em vez de reduzir toda falha a “rastreamento indisponível”.
Não presuma que um código numérico da aplicação tenha o mesmo significado que um código de status HTTP. Seus significados vêm de camadas diferentes e devem ser interpretados separadamente.
3. Resultado no nível da remessa
Para registros em lote, contabilize cada item enviado. Uma resposta pode distinguir remessas aceitas e rejeitadas; seu analisador deve seguir o esquema exato documentado para a versão selecionada. Não marque um lote inteiro como registrado apenas porque um item foi bem-sucedido.
Normalize as respostas do provedor em estados estáveis da sua própria aplicação. Por exemplo, seu banco de dados pode usar accepted, rejected e uncertain. Esses são estados internos sugeridos, não valores literais de resposta do 17TRACK. Mantenha a resposta original do provedor disponível sob uma política adequada de retenção e acesso para que os desenvolvedores possam investigar discrepâncias.
Um registro de registro útil contém o ID interno da remessa, o número enviado, a seleção da transportadora, o horário da tentativa, a versão da API, o resultado e os detalhes do erro do provedor. Mantenha o status do registro separado do status da entrega.
Trate as tentativas novamente sem criar um loop infinito
A política de novas tentativas deve depender da falha, e não simplesmente de ter ocorrido uma exceção.
- Entrada inválida: corrija o campo antes de tentar novamente. Repetir uma solicitação malformada inalterada provavelmente não ajudará.
- Falha de autenticação: verifique as credenciais e a configuração da conta. Evite enviar repetidamente o mesmo lote com falha.
- Limitação de taxa: siga os limites documentados e quaisquer instruções de nova tentativa aplicáveis. Use um backoff limitado em vez de novas tentativas paralelas imediatas.
- Falha temporária do serviço: tente novamente dentro de um orçamento definido de tentativas e tempo.
- Tempo limite após o envio: reconcilie o estado de registro da remessa usando o comportamento documentado da API antes de presumir que a primeira tentativa falhou.
- Resposta relacionada a duplicidade: verifique se a remessa já está registrada e corretamente associada ao registro da sua aplicação.
Não presuma que o registro seja idempotente, a menos que a documentação defina esse comportamento. A desduplicação no lado da aplicação reduz envios repetidos acidentais, mas não estabelece a política do provedor para tratamento de duplicidades.
Use uma regra de exclusividade interna adequada ao seu modelo de remessa. O número de rastreamento sozinho pode não ser uma chave permanente suficiente entre transportadoras e longos períodos de retenção. Preserve o contexto da transportadora e seu próprio identificador de remessa, e documente como substituições e números corrigidos são tratados.
Monitore o registro separadamente das atualizações de rastreamento
O monitoramento da API deve distinguir uma falha de integração de uma remessa que simplesmente não tem um novo evento da transportadora. Essas condições exigem responsáveis e correções diferentes.
Para o registro, monitore as contagens de aceitações e rejeições, categorias de erro, resultados incertos, fila de novas tentativas e latência das respostas. Para o rastreamento subsequente, monitore separadamente o recebimento de atualizações ou as falhas de recuperação. Evite atribuir limites numéricos de alerta até entender o tráfego normal e os limites operacionais documentados pelo provedor.
Uma verificação prática de produção deve responder:
- Toda remessa aguardando rastreamento tem um registro de registro?
- Todo registro aceito pode ser rastreado até o pacote correto?
- Os itens rejeitados são encaminhados a alguém que possa corrigir os dados subjacentes?
- As solicitações incertas são reconciliadas, em vez de abandonadas ou repetidas indefinidamente?
- Os status exibidos aos clientes são derivados dos eventos da remessa, e não da aceitação do registro?
- As credenciais e as informações pessoais desnecessárias são excluídas dos logs?
Para operações de comércio eletrônico, a transferência operacional é tão importante quanto a chamada da API. Os desenvolvedores devem ser responsáveis pelas falhas de transporte e análise; as equipes de envio ou atendimento devem conseguir investigar etiquetas incorretas, mapeamentos de transportadoras e informações de remessa ausentes.
FAQ
Posso registrar um número de rastreamento antes do primeiro escaneamento da transportadora?
O registro e os escaneamentos da transportadora são eventos separados. Um serviço pode aceitar um número antes que os eventos de rastreamento estejam disponíveis, sujeito às suas regras de validação. Não interprete a aceitação como prova de que a transportadora recebeu o pacote.
Sempre preciso fornecer um código de transportadora?
Isso depende do comportamento de detecção documentado pela API e da remessa envolvida. Se a transportadora for conhecida, um identificador explícito e corretamente mapeado pode reduzir a ambiguidade. Se ela for desconhecida, use o método documentado de detecção automática em vez de inventar um valor de transportadora.
Por que a API retornou sucesso HTTP enquanto uma remessa falhou?
A solicitação HTTP pode ser bem-sucedida enquanto a aplicação rejeita um item individual. Leia o resultado geral da aplicação e os resultados no nível da remessa. Essa distinção é particularmente importante para solicitações em lote.
O que devo fazer quando uma solicitação de registro atinge o tempo limite?
Trate o resultado como incerto. O servidor pode ter processado a solicitação antes que a conexão falhasse. Verifique o comportamento documentado do provedor para duplicidades e os métodos disponíveis de consulta de registro ou rastreamento; depois reconcilie ou tente novamente dentro de uma política limitada.
O registro configura automaticamente as notificações de rastreamento?
Não presuma que sim. Registro, recuperação de rastreamento e configuração de webhooks são aspectos separados da integração. Verifique a documentação relevante e teste o fluxo completo de atualização antes de depender dele para notificações aos clientes.
Fontes
- Documentação da API do 17TRACK — referência para endpoints de registro, autenticação, campos de solicitação, identificadores de transportadoras, esquemas de resposta e tratamento de erros. Ajuste os detalhes da implementação à versão da API implantada.
- Visão geral da Tracking API do 17TRACK — ponto de partida oficial para o produto de API de rastreamento e os recursos de integração para desenvolvedores.


