Conectar o FedEx Freight: obter cotações LTL e rastrear cargas
Obtenha um Client ID e um Client Secret no FedEx Developer Portal, preencha-os com seu número de conta Freight no Integration, teste primeiro com credenciais sandbox e depois mude test_mode para produção para cotações LTL e rastreamento reais.
O conector do FedEx Freight é para carga fracionada (LTL). Ele obtém cotações de tarifa LTL e rastreia envios de carga por número de rastreamento ou número PRO, retornando os eventos de leitura. Ele não cria etiquetas de envio e não é a conexão de pacotes pequenos da FedEx: usa seus próprios campos e sua conta FedEx Freight. A conexão usa o ambiente sandbox por padrão, então leia a etapa de teste com atenção antes de passar para produção.
Pré-requisitos#
- Um app no FedEx Developer Portal, para poder ler seu Client ID e seu Client Secret.
- Seu número de conta FedEx Freight: a conta Freight usada para cotação e faturamento LTL. Uma conta de pacotes pequenos da FedEx é outra conta para esta conexão.
- Uma escolha clara de ambiente para o primeiro teste: credenciais sandbox com o ambiente sandbox, ou credenciais de produção com produção. A conexão usa sandbox por padrão, e credenciais sandbox e de produção não se misturam.
- Pelo menos uma rota real que você possa cotar, e um número de rastreamento ou número PRO de um envio de carga anterior, para verificar cotações e rastreamento após o teste.
Obter credenciais#
- Entre no FedEx Developer Portal e abra seu app.
- No seu app, leia o Client ID e o Client Secret. Os dois valores formam um par OAuth2 e pertencem juntos: pegue os dois do mesmo app.
- Anote seu número de conta FedEx Freight, a conta Freight usada para cotação e faturamento LTL.
- Decida com qual conjunto de credenciais você testará primeiro. Credenciais sandbox são testadas no endereço sandbox https://apis-sandbox.fedex.com; credenciais de produção em https://apis.fedex.com. Anote qual conjunto escolheu: o campo test_mode deve corresponder a ele.
Preencher no Integration#
- Abra o Integration, escolha FedEx Freight e inicie uma nova conexão.
- client_id, obrigatório, Client ID: o Client ID de FedEx Developer Portal → seu app, no formato l7xxxxxx e os caracteres seguintes. Copie do mesmo app que o segredo abaixo.
- client_secret, obrigatório, Client Secret: o Client Secret do mesmo app no FedEx Developer Portal. É guardado como segredo.
- account_number, obrigatório, Freight Account Number: seu número de conta FedEx Freight, por exemplo no formato 123456789. É a conta Freight usada para cotação e faturamento LTL, não uma conta de pacotes.
- test_mode, opcional, Test Mode: preencha true para usar o ambiente sandbox https://apis-sandbox.fedex.com, que também é o padrão quando o campo fica vazio. Preencha false para usar produção https://apis.fedex.com. O valor deve corresponder às credenciais preenchidas: credenciais sandbox com true, credenciais de produção com false.
Testar a conexão#
Clique em Testar a conexão. O que acontece depende do que você preencheu. Se client_id, client_secret ou account_number estiver ausente, o teste não envia nenhuma solicitação à FedEx: ele executa uma verificação de ensaio local com dados de exemplo e relata sucesso só para esse ensaio. Leia o detalhe do resultado: um sucesso de ensaio não prova suas credenciais. Quando os três valores estão presentes, o teste roda de verdade em duas etapas: primeiro troca seu client_id e client_secret por um token OAuth2, depois envia uma chamada pequena de cotação LTL com sua conta Freight. Uma resposta 401 ou 403 conta como falha de autenticação; outras respostas do endpoint de cotação contam como alcançável. Um sucesso real se lê assim: autenticação OAuth2 aprovada para o endereço do ambiente, e endpoint de cotação Freight alcançável. O teste espera até 12 segundos.
Mapping / escolher modelo#
Escolha o modelo padrão do FedEx Freight para cotação e rastreamento LTL. As cotações saem com seu número de conta Freight, e as consultas de rastreamento aceitam um número de rastreamento ou um número PRO e devolvem os eventos de leitura. Depois que o teste aprovar de verdade, faça uma cotação numa rota que você conhece e compare a tarifa e o serviço devolvidos com o que você espera para essa rota; depois busque um envio anterior pelo número PRO e compare os eventos de leitura. Ative só quando as duas conferências estiverem certas.
Ativar#
Após ativar, a conexão obtém cotações LTL reais com sua conta Freight e rastreia envios de carga por número de rastreamento ou número PRO. Para passar do teste ao trabalho real, defina test_mode como false e confirme que o client_id e o client_secret da conexão são os valores do seu app de produção: uma conexão que fica em sandbox continua devolvendo resultados sandbox. Acompanhe as primeiras cotações e consultas de rastreamento em Runs / Logs antes de deixar a conexão sem supervisão.
O que esta conexão não faz: não cria nem compra etiquetas de envio, e não cuida do envio de pacotes pequenos da FedEx. Para tarifas e etiquetas de pacotes, use a conexão separada de pacotes pequenos da FedEx, com suas próprias credenciais e conta.
Perguntas frequentes#
O teste falha com 401 ou 403
A FedEx recusou a autenticação: a solicitação de token OAuth2 ou a chamada de cotação foi rejeitada com 401 ou 403. A conexão trata 401 e 403 como falha de autenticação, então o client_id, o client_secret ou o ambiente ao qual pertencem não corresponde.
Copie client_id e client_secret de novo do mesmo app em FedEx Developer Portal → seu app, confira se test_mode corresponde a esse conjunto de credenciais (sandbox com true, produção com false) e teste novamente.
Credenciais de produção falham no teste de imediato
A conexão continua apontando para o sandbox. test_mode usa por padrão o ambiente sandbox https://apis-sandbox.fedex.com quando está vazio ou em true, e credenciais de produção não valem no sandbox: então um Client ID e um Secret de produção corretos falham mesmo assim.
Defina test_mode como false para que o teste rode na produção https://apis.fedex.com, mantenha o client_id e o client_secret de produção, salve e teste novamente. Para testar no sandbox, mantenha test_mode como true e use credenciais sandbox.
O teste diz sucesso, mas nenhuma cotação real foi feita
Um dos três valores obrigatórios estava vazio ao testar. Se client_id, client_secret ou account_number estiver ausente, o teste não envia nenhuma solicitação à FedEx e só executa uma verificação de ensaio local com dados de exemplo: sua mensagem de sucesso diz que a verificação rodou sem credenciais reais e sem uma solicitação real.
Preencha os três valores (client_id e client_secret de FedEx Developer Portal → seu app, e seu número de conta Freight em account_number), salve e teste novamente. Só um sucesso que nomeia o endereço do ambiente e o endpoint de cotação Freight conta como teste real de credenciais.
As cotações funcionam, mas o rastreamento não retorna nada para um envio
O número usado não é um número de rastreamento ou número PRO do FedEx Freight para esta conta, ou o envio ainda não tem eventos de leitura. O rastreamento nesta conexão lê envios de carga por número de rastreamento ou número PRO: um número de rastreamento de pacotes não retornará eventos de carga.
Copie o número PRO ou o número de rastreamento da documentação de carga de um envio já coletado, confira dígito por dígito e busque de novo. Se um envio coletado conhecido continuar sem retornar nada, confirme que o envio se moveu na mesma conta Freight da conexão.
Esta conexão pode criar etiquetas do FedEx Freight?
Não. Esta conexão cobre só cotações LTL e rastreamento de carga: não há criação de etiquetas nela. Procurar uma etapa de etiquetas nesta conexão não encontrará nenhuma, porque o trabalho Freight aqui é cotar e rastrear.
Use esta conexão para a cotação e o rastreamento do envio de carga, e mantenha o trabalho de etiquetas e de reserva no canal onde você contrata a carga. Para etiquetas de pacotes pequenos da FedEx, use em vez disso a conexão separada de pacotes pequenos da FedEx.