Conectar a FedEx: tarifas ao vivo, etiquetas e rastreio
Obtenha a API Key e a Secret Key do seu projeto no FedEx Developer Portal e seu FedEx Account Number de 9 dígitos, cole no Integration, teste, mapeie serviços e comece a cotar e enviar.
O conector da FedEx obtém tarifas ao vivo, compra etiquetas, rastreia envios e anula etiquetas pela API da FedEx, tudo na sua própria conta FedEx. Tarifas e cobranças de etiquetas são faturadas no FedEx Account Number que você preencher.
Pré-requisitos#
- Uma conta FedEx com um FedEx Account Number de 9 dígitos: tarifas e etiquetas são faturadas nesta conta.
- Acesso a FedEx Developer Portal → My Projects, onde são exibidas a API Key e a Secret Key do seu projeto.
- Decida primeiro o ambiente: preencha sandbox com true para testar no sandbox, ou deixe em branco para produção. Credenciais de sandbox e produção não se misturam: use as do ambiente escolhido.
Obter credenciais#
- Obtenha a API Key: vá a FedEx Developer Portal → My Projects → seu projeto → API Key. Essa API Key é o OAuth Client ID do seu projeto: copie exatamente como exibida.
- Obtenha a Secret Key: no mesmo projeto, abra Secret Key: é o OAuth Client Secret. O valor completo só é exibido por completo ao ser gerado, então guarde-o em local seguro imediatamente. Se perdê-lo, gere um novo no portal.
- Obtenha o FedEx Account Number: vá a fedex.com → My Profile → Account Management e copie seu número de conta de envio de 9 dígitos. Tarifas e etiquetas serão faturadas nesta conta.
- Aviso: mantenha os projetos separados. Track e Rate / Ship podem pertencer a dois projetos separados do Developer Portal, cada um com sua própria API Key e Secret Key. Para uma conexão, use sempre a API Key e a Secret Key do mesmo projeto. Misturar a Key de um projeto com o Secret do outro falhará.
Preencher no Integration#
- Abra Integration → Marketplace → FedEx → Nova conexão.
- API Key: cole a API Key de FedEx Developer Portal → My Projects → seu projeto. É o OAuth Client ID desse projeto. É guardada como segredo e nunca exibida.
- Secret Key: cole a Secret Key do mesmo projeto. Certifique-se de que ela combina com a API Key acima: não use a Secret Key de outro projeto, por exemplo a do projeto Track quando esta conexão é para Rate / Ship. É guardada como segredo e nunca exibida.
- FedEx Account Number: preencha seu número de conta de envio de 9 dígitos de fedex.com → My Profile → Account Management, por exemplo 123456789. Confira cada dígito: o teste não verifica este número, mas tarifas e etiquetas são faturadas nele.
- Use sandbox, opcional: preencha true para usar o sandbox, ou deixe em branco para produção. Preencha true apenas junto com credenciais do projeto sandbox; deixe em branco apenas junto com credenciais do projeto de produção.
Testar a conexão#
Clique em Testar a conexão. O teste apenas troca sua API Key e Secret Key por um token OAuth para verificar se as credenciais funcionam no ambiente escolhido. Ele não verifica o FedEx Account Number nem cota tarifa, então um teste aprovado confirma apenas a Key e o Secret: se o número da conta estiver errado, tarifas e etiquetas ainda podem falhar depois. Se o teste falhar, anote o erro e veja a FAQ.
Mapping / escolher modelo#
A FedEx não precisa de mapping de pedidos: trabalha com pacotes, não com pedidos. O que você mapeia aqui são serviços: mapeie cada serviço da FedEx ao seu serviço interno correspondente (mapeamento de serviços) e habilite apenas os serviços da FedEx que você realmente usa para enviar. A comparação de tarifas e a compra de etiquetas seguem esse mapeamento, então o pedido só cota e compra o serviço pretendido.
Ativar#
Após ativar, a conexão serve para comparar tarifas e comprar etiquetas ao enviar, as atualizações de rastreio voltam e são registradas no envio, e etiquetas que você não precisa mais podem ser anuladas pela mesma conexão. Acompanhe os primeiros envios em Runs / Logs, principalmente a primeira cotação e a primeira etiqueta, antes de deixar sem supervisão.
Perguntas frequentes#
O teste falha com 401
A API Key ou a Secret Key está incorreta, ou as duas foram misturadas entre projetos, por exemplo a API Key do projeto Rate / Ship com a Secret Key do projeto Track. A FedEx só aceita uma Key e um Secret do mesmo projeto, então um par misturado é rejeitado.
Abra um único projeto em FedEx Developer Portal → My Projects, copie novamente sua API Key e sua Secret Key desse mesmo projeto sem espaços extras, substitua os dois campos e teste novamente.
Credenciais de sandbox e produção misturadas
O ambiente e as credenciais não coincidem. O campo sandbox indica um ambiente, true para sandbox e em branco para produção, mas a API Key e a Secret Key vêm de um projeto do outro ambiente, então a FedEx rejeita a troca de token.
Escolha um ambiente e faça tudo coincidir com ele: para testar, defina Use sandbox como true e preencha as credenciais do projeto sandbox; para envios reais, deixe Use sandbox em branco e preencha as credenciais do projeto de produção. Depois teste novamente.
O teste passa, mas tarifas ou etiquetas falham
O FedEx Account Number está incorreto. O teste apenas troca um token OAuth e nunca verifica o número da conta, então uma conta digitada errada ou trocada ainda passa no teste: a falha só aparece quando uma tarifa ou etiqueta tenta faturar nessa conta.
Verifique a conta em fedex.com → My Profile → Account Management, corrija o campo FedEx Account Number com o número exato de 9 dígitos exibido lá e tente a cotação ou a etiqueta novamente.
Etiqueta criada, mas o rastreio nunca atualiza
As atualizações de rastreio chegam no ritmo da FedEx, não na hora, então uma etiqueta nova pode ficar sem movimentação por um tempo. Se o pacote nunca foi entregue à FedEx, também ainda não há leitura para reportar.
Confirme primeiro que o pacote foi entregue à FedEx. Se o rastreio continuar sem mostrar nada depois que o pacote entrou na rede da FedEx, verifique Runs / Logs em busca de erros de rastreio e confirme que a conexão usada para rastreio tem a API Key e a Secret Key do projeto Track, não o par de Rate / Ship.