API de Rastreamento da FedEx: Como Rastrear Pacotes Passo a Passo

Para rastrear pacotes FedEx por meio de um aplicativo, crie uma conta FedEx Developer, obtenha as credenciais da API, solicite um token de acesso OAuth, envie uma solicitação de rastreamento e mapeie a resposta para o fluxo de pedidos ou remessas. A FedEx Tracking API destina-se a sistemas de software que precisam de dados sobre o status das remessas, enquanto o site da FedEx geralmente é mais rápido para verificar manualmente um pacote.

Este guia explica a sequência de integração, as informações que devem ser validadas, erros comuns de implementação e uma alternativa para empresas que precisam de rastreamento de várias transportadoras em vez de conectividade exclusiva com a FedEx. Os campos exatos das solicitações, as regras de autenticação, os ambientes e a disponibilidade do serviço devem sempre ser confirmados na documentação atual da FedEx antes da implantação em produção.

Escolha primeiro o método de rastreamento adequado

O melhor método depende de quem realizará a ação e de quantas remessas precisam ser monitoradas.

• Consulta pontual: Use a página de rastreamento da FedEx quando um cliente ou agente de suporte precisar verificar apenas uma remessa.
• Aplicativo interno: Use a FedEx Tracking API quando um sistema de gerenciamento de pedidos, aplicativo de armazém, portal do cliente ou ferramenta de suporte precisar de dados de status programáticos.
• Operação com várias transportadoras: Considere uma plataforma de rastreamento quando a empresa receber remessas da FedEx e de outras transportadoras e quiser uma integração normalizada, um modelo de status único ou uma experiência de rastreamento voltada ao cliente.

Uma integração de API exclusiva da FedEx pode oferecer controle direto e ser adequada para um sistema desenvolvido em torno de remessas da FedEx. Isso também significa que sua equipe deverá gerenciar por conta própria a autenticação, os limites de solicitações, as alterações nas respostas, a lógica de status específica da transportadora, o tratamento de erros e quaisquer integrações adicionais com outras transportadoras.

O que você precisa antes de usar a FedEx Tracking API

Prepare os seguintes itens antes de escrever a integração:

• Uma conta FedEx Developer e acesso ao portal de desenvolvedores da FedEx.
• As credenciais da API necessárias para o ambiente FedEx selecionado. A documentação da FedEx pode mencionar credenciais como um ID do cliente e um segredo do cliente.
• Um relacionamento de conta FedEx ou outras informações da conta, caso a operação de API selecionada exija isso.
• Um local seguro no lado do servidor para armazenar as credenciais. Não exponha o segredo do cliente em JavaScript do navegador, em um aplicativo móvel ou em um repositório público.
• Pelo menos um identificador de remessa válido para testes, como um número de rastreamento FedEx. Os dados de teste devem representar os tipos de remessa e serviços que seu aplicativo processará.
• Um plano para armazenar o último status conhecido, o horário do evento, as informações de localização e o horário da verificação bem-sucedida mais recente.

A FedEx separa o acesso de desenvolvedor, a autenticação, os ambientes de API e os requisitos operacionais. Um login bem-sucedido no portal de desenvolvedores, por si só, não comprova que uma solicitação de produção está pronta. Consulte a documentação atual do produto para verificar pré-requisitos da conta, requisitos de aprovação, URLs dos ambientes e quaisquer restrições de uso.

Etapa 1: Crie um aplicativo no portal de desenvolvedores da FedEx

Comece pelo FedEx Developer Portal oficial e identifique o produto Track API. Crie ou selecione um aplicativo e registre as credenciais fornecidas para o ambiente que pretende usar. Mantenha separadas as credenciais de desenvolvimento e de produção.

Nesta etapa, confirme quatro detalhes:

1. Qual produto de API contém a operação de rastreamento necessária.
2. Qual URL base pertence ao ambiente de teste ou de produção.
3. Qual método de autenticação e quais escopos, se houver, são necessários.
4. Se a solicitação precisa de um número de conta FedEx ou de outro campo no nível da conta.

Não copie uma URL ou um nome de campo de um exemplo de código antigo sem consultar a documentação atual. As APIs de transportadoras podem alterar versões de endpoints, cabeçalhos obrigatórios, estruturas de resposta ou regras de integração.

Etapa 2: Solicite um token de acesso OAuth

A autenticação da API da FedEx geralmente usa as credenciais de cliente do OAuth 2.0. Seu aplicativo envia as credenciais do cliente ao endpoint de autorização da FedEx e recebe um token de acesso de curta duração. Em seguida, o aplicativo envia esse token no cabeçalho Authorization da solicitação de rastreamento.

Um exemplo simplificado de linha de comando é semelhante a este:

curl -X POST "<FEDEX_OAUTH_URL>" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=<CLIENT_ID>" \
  -d "client_secret=<CLIENT_SECRET>"

Considere isso um padrão de implementação, não um substituto para a documentação atual de autenticação da FedEx. O código de produção deve ler o valor de expiração do token, armazená-lo em cache com segurança e solicitar um novo token quando ele expirar ou quando a API retornar uma falha de autenticação. Evite solicitar um novo token para cada número de rastreamento, a menos que os limites oficiais e o seu padrão de tráfego tornem isso necessário.

Entre as proteções úteis de autenticação estão:

• Armazene os segredos em um gerenciador de segredos no lado do servidor ou em variáveis de ambiente protegidas.
• Nunca grave tokens de acesso ou segredos do cliente nos logs do aplicativo.
• Use credenciais separadas para desenvolvimento e produção quando a plataforma oferecer suporte a essa separação.
• Retorne um erro controlado ao usuário quando a autenticação falhar; não exponha a resposta bruta da transportadora.
• Monitore as falhas de token separadamente das falhas de números de rastreamento inválidos.

Etapa 3: Crie a solicitação de rastreamento

Depois de obter um token válido, construa a solicitação descrita na documentação atual da FedEx Track API. A solicitação geralmente identifica um ou mais registros de remessa e pode incluir opções que afetam o nível de detalhe retornado. Os nomes exatos das propriedades JSON e os campos obrigatórios devem vir da versão do endpoint da FedEx que você está usando.

Um padrão representativo de solicitação pode ser semelhante a este:

curl -X POST "<FEDEX_TRACK_BASE_URL>/track/v1/trackingnumbers" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "trackingInfo": [
      {
        "trackingNumberInfo": {
          "trackingNumber": "<FEDEX_TRACKING_NUMBER>"
        }
      }
    ],
    "includeDetailedScans": true
  }'

O caminho do endpoint e os nomes dos campos acima devem ser conferidos na documentação atual da FedEx antes do uso. Algumas integrações podem precisar de um formato de solicitação diferente, de um número de conta, de uma consulta baseada em referência ou de outra opção para leituras detalhadas. Não presuma que um número de rastreamento pertencente a outra transportadora possa ser enviado a um endpoint exclusivo da FedEx.

Etapa 4: Analise a resposta e converta-a em campos de negócio

Não passe a resposta completa da transportadora diretamente para uma página voltada ao cliente. Primeiro, mapeie-a para um modelo interno estável. Um registro prático de remessa pode incluir:

• Transportadora: FedEx.
• Identificador de rastreamento: O identificador enviado à API.
• Status atual: Seu status normalizado, como etiqueta criada, em trânsito, saiu para entrega, entregue, exceção ou desconhecido.
• Status da transportadora: O status ou código original da FedEx, mantido para suporte e depuração.
• Evento mais recente: A descrição e o horário do evento mais recente retornado pela FedEx.
• Entrega estimada: Armazene somente quando a resposta a fornecer e exiba-a como uma estimativa, não como uma garantia.
• Confirmação de entrega: Use a resposta da transportadora para determinar se a entrega foi informada.
• Horário da última verificação: O horário registrado pelo seu sistema, que é diferente do horário do evento informado pela FedEx.

A normalização de status exige julgamento editorial e operacional. Por exemplo, uma exceção não deve ser exibida automaticamente como uma entrega malsucedida, e um evento de etiqueta criada não significa necessariamente que o pacote esteja se movimentando pela rede. Preserve o evento original da transportadora junto com o status normalizado para que a equipe de suporte possa investigar diferenças.

Etapa 5: Trate erros e informações incompletas

Uma integração de rastreamento em produção deve distinguir entre diferentes tipos de falha. Uma solicitação malformada, um token expirado, um número de rastreamento inválido, uma indisponibilidade temporária da transportadora e uma resposta bem-sucedida sem nenhum evento útil não representam a mesma condição.

Situação	Tratamento recomendado
Falha de autenticação	Atualize as credenciais ou o tratamento do token e alerte o responsável pela integração se o problema continuar.
Solicitação inválida	Valide o payload, os cabeçalhos obrigatórios, o formato do identificador e o ambiente antes de tentar novamente.
Número de rastreamento não encontrado	Exiba um estado não resolvido ou indisponível; não informe ao cliente que o pacote foi perdido sem evidências adicionais.
Tempo limite temporário ou erro do servidor	Use novas tentativas limitadas com recuo e mantenha o último status conhecido.
Nenhuma leitura recente	Exiba o último evento confirmado e seu tempo decorrido, em vez de inventar uma localização atual.

A lógica de novas tentativas deve ser conservadora. Solicitações repetidas podem aumentar a carga, gerar alertas excessivos ou entrar em conflito com os limites da API. Aplique tempos limite, recuo exponencial, processamento idempotente e monitoramento de falhas repetidas. Os limites exatos de taxa e os compromissos de serviço devem ser obtidos do seu contrato com a FedEx ou da documentação atual, e não presumidos com base em um aplicativo de exemplo.

Etapa 6: Programe atualizações sem criar uma experiência ruim para o cliente

A maioria dos sistemas de remessa não precisa solicitar um novo resultado a cada poucos segundos. Use uma estratégia de atualização baseada no estado da remessa. Uma nova remessa pode precisar de verificações mais frequentes após a criação da etiqueta, enquanto uma remessa entregue normalmente deve parar de ser consultada. Uma exceção pode exigir um fluxo de suporte separado, em vez de consultas automatizadas mais rápidas.

Ao apresentar resultados aos clientes, inclua o horário do evento mais recente da transportadora e deixe claro se a data de entrega é estimada. Se a API estiver temporariamente indisponível, mantenha o último resultado verificado e explique que o status não foi atualizado. Isso é mais útil do que substituir um status conhecido por um erro genérico.

Etapa 7: Teste o fluxo de trabalho completo

Teste mais do que uma resposta bem-sucedida. Um plano de testes realista deve abranger:

• Um número de rastreamento válido com vários eventos de leitura.
• Uma remessa recém-criada com histórico de rastreamento limitado.
• Uma remessa entregue.
• Uma remessa com exceção ou atrasada, se houver dados de teste representativos.
• Um número de rastreamento inválido ou incompleto.
• Uma credencial expirada ou revogada.
• Um tempo limite, uma resposta de limite de taxa e um erro temporário do servidor.
• Eventos duplicados e eventos que chegam fora de ordem.
• Diferentes fusos horários e transições para o horário de verão.
• Redação de credenciais, tokens, dados pessoais e payloads completos da transportadora nos logs.

Antes de entrar em produção, compare seu status normalizado com a página de rastreamento da FedEx para uma amostra controlada. As duas visualizações podem não ser atualizadas exatamente no mesmo momento; portanto, o objetivo é confirmar que seu analisador interpreta corretamente a resposta e não transforma dados ausentes em uma afirmação definitiva.

Quando uma API de rastreamento de várias transportadoras é mais adequada

Uma integração direta com a FedEx faz sentido quando a FedEx é a principal transportadora e sua equipe deseja assumir toda a lógica do aplicativo. Ela é menos eficiente quando os pedidos podem passar por várias transportadoras, marketplaces, operadores postais ou serviços regionais de entrega. Nessa situação, a empresa pode precisar de detecção de transportadora, um modelo de status comum, orquestração por webhook ou consultas, páginas de rastreamento com a marca e uma única visão de suporte.

A 17TRACK oferece uma Tracking API separada e publica documentação para desenvolvedores em api.17track.net. Ela pode ser avaliada como uma opção de várias transportadoras quando o requisito é mais amplo do que o rastreamento exclusivo da FedEx. A escolha certa depende das transportadoras, países, detalhes dos eventos, modelo de integração, termos comerciais e controles operacionais que seu projeto possa verificar durante os testes. Um serviço de várias transportadoras não elimina a necessidade de testar exceções específicas de cada transportadora nem de validar a precisão e o momento dos eventos para o seu próprio conjunto de remessas.

Lista de verificação prática de implementação

• Confirme se o produto da API da FedEx corresponde ao tipo de consulta necessário.
• Verifique o endpoint de autenticação, a URL base, o esquema da solicitação e os cabeçalhos obrigatórios atuais.
• Mantenha os segredos do cliente e os tokens de acesso no servidor.
• Armazene em cache e atualize os tokens OAuth com segurança.
• Valide os identificadores de rastreamento antes de enviar as solicitações.
• Armazene tanto o status original da transportadora quanto o status normalizado.
• Registre o horário do evento da transportadora separadamente do horário de recuperação do seu sistema.
• Use novas tentativas limitadas e monitore separadamente erros de autenticação, validação, tempo limite e da transportadora.
• Interrompa as consultas de rotina após um estado terminal, de acordo com suas regras operacionais.
• Teste variações reais de resposta antes de expor mensagens de status aos clientes.
• Consulte novamente a documentação da FedEx ao alterar versões da API ou ampliar os tipos de remessa.

FAQ

Posso usar o site da FedEx em vez da API?

Sim. O site da FedEx geralmente é a opção mais simples para uma consulta manual. Uma API se torna útil quando o software precisa recuperar dados de rastreamento automaticamente, conectar eventos de status aos pedidos ou apresentar informações de rastreamento dentro de outro aplicativo.

Preciso de um token OAuth para cada solicitação de rastreamento?

Normalmente, o aplicativo obtém um token de acesso e o envia com as solicitações de API subsequentes até que ele expire. Armazene o token em cache com segurança e siga a documentação atual de autenticação da FedEx para conhecer o comportamento de expiração e atualização. Não exponha o token ao navegador ou ao cliente.

A API pode me informar exatamente onde está um pacote?

Ela pode retornar os eventos de rastreamento e outras informações fornecidas pela FedEx para a remessa. O resultado pode mostrar uma localização de leitura ou instalação, mas não deve ser interpretado como posicionamento GPS contínuo em tempo real. Exiba somente a localização e os detalhes do evento efetivamente retornados.

Por que às vezes um número de rastreamento não apresenta atualização?

Uma remessa pode ter sido criada sem uma leitura recente, o identificador pode estar incorreto, o evento pode ainda não estar disponível na resposta ou o serviço da transportadora pode estar temporariamente indisponível. Mantenha o último resultado confirmado, mostre quando ele foi verificado e investigue falhas repetidas em vez de declarar que a remessa foi perdida.

Uma empresa de comércio eletrônico deve criar APIs separadas para cada transportadora?

Isso pode ser razoável para uma operação focada na FedEx e com recursos sólidos de engenharia. Uma empresa que envia por várias transportadoras pode preferir uma camada de rastreamento de várias transportadoras para reduzir o trabalho de integração e normalizar os eventos. Compare a cobertura das transportadoras, o nível de detalhes dos dados, a confiabilidade, a documentação, o custo e o controle sobre as experiências voltadas ao cliente antes de escolher.

Fontes

• FedEx Developer Portal: Track API
• FedEx Developer Portal: Authorization API
• FedEx Developer Portal
• 17TRACK Tracking API
• 17TRACK API Documentation