info-icon


MAIN MENU

Boas Práticas para a Integração de API FedEx

Este guia de referência rápida destina-se a ajudar os consumidores da API a compreender as formas de melhorar a experiência de integração com a FedEx e garantir a qualidade da solução de integração em termos de design, velocidade e segurança.

Para integrar de forma eficiente com as API FedEx, os programadores devem seguir estas boas práticas para a integração:

URI de API

  • Existem diferentes URI de API para testes e produção. 
  • Os programadores devem utilizar os URI de teste para testes de desenvolvimento e integração e os URI de produção para produção.

Os URI de API encontram-se indicados abaixo:

Teste: https://apis-sandbox.fedex.com/

Produção: https://apis.fedex.com/

Gestão de credenciais

  • Chave de API e Chave Secreta

  • A Chave de API e a Chave Secreta são utilizadas para identificar a sua aplicação e têm de ser utilizadas num pedido de token OAuth.
  1. A Chave de API e a Chave Secreta devem ser utilizadas de forma muita segura. Não distribua a Chave de API ou a Chave Secreta por e-mail ou código distribuído, incluindo JavaScript do lado do cliente.
  2. A sua aplicação será comprometida se a Chave de API ou a Chave Secreta forem roubadas. Se suspeitar que as suas credenciais foram roubadas ou comprometidas, recrie de imediato a Chave Secreta.
  3. Evite registar informações confidenciais, como a Chave Secreta.
  • Não codifique a Chave da API ou a Chave no seu código.
  • A sua aplicação deve ser dinamicamente capaz de atualizar a Chave de API e a Chave Secreta.
  • As credenciais do cliente devem ser armazenadas num cofre/local seguro para que não possam ser comprometidas.

  • Token OAuth

  • O token de acesso deve ser armazenado apenas no servidor da aplicação web e não deve ser exposto ao browser.
  • Não codifique o token nas suas aplicações.
  • Proteja os tokens de acesso para evitar comprometê-los.
  • Evite efetuar várias chamadas à API do token OAuth para um novo token de acesso. É recomendado colocar em cache o token de acesso até observar o código de erro HTTP 401. Volte a gerar o token OAuth nessa altura.
  • Não exponha o token ao utilizador final ou à aplicação.
  • Utilize HTTPS para qualquer transação da API.

Práticas de codificação

  • Para manter a conformidade com o protocolo de comunicação de encriptação de dados mais recente e seguro, recomenda-se a utilização do protocolo Transport Layer Security (TLS), versão 1.2 ou superior.
  • Não se esqueça de definir os cabeçalhos adequados da API necessários para cada pedido da API. Encontrará as informações referentes ao cabeçalho em cada página de documentação da API. 
  • O "Content-Type" em HTTP POST deve ser "application/json".
  • Consulte o código de amostra para começar a utilizar cada API. Cada ponto final de API é acompanhado por várias amostras que irão ajudar a compreender os elementos e formatos necessários, bem como outros detalhes.
  • Quando os utilizadores ou programadores enviam várias casas decimais nos seus valores, tal pode causar erros estranhos. Para o valor/montante de peso e moeda, apenas são permitidas duas casas decimais explícitas. As dimensões (como o comprimento, largura e altura) não suportam casas decimais.

    • Por exemplo: peso: 45,26; valor/montante de moeda: 100,52; comprimento: 10; largura: 25; altura: 15.

  • Evite enviar elementos em branco.

    • Por exemplo: "Streetlines":""

  • Envie apenas os dados necessários para processar o pedido.

    • Por exemplo, para uma expedição nacional nos EUA, evite enviar a fatura comercial e os dados da mercadoria que apenas seriam obrigatórios para expedições internacionais.

  • Durante a programação, determine a reação caso um elemento de resposta não obrigatório, como uma tarifa, não seja devolvido. Avalie a resposta da transação para elementos em falta antes de utilizar os dados.

    • Por exemplo, é possível expedir um volume se as tarifas não estiverem funcionais. Teste a resposta da transação para elementos em falta antes de utilizar os dados.

  • De modo geral, evite dependências fortes da integração da API FedEx quando aplicável.
  • De modo a reduzir a latência e obter resultados precisos, devem ser utilizadas as seguintes funcionalidades:
    • Filtragem: utilize esta funcionalidade para limitar a pesquisa com os parâmetros que procura.
    • Ordenação: utilize esta funcionalidade para ordenar os resultados por um determinado parâmetro em ordem ascendente ou descendente.
  • Valide a presença de dados nos campos obrigatórios (como o código postal do destinatário e o peso do volume) antes de enviar a transação. Valide a conformidade dos dados para o campo em questão. Isto irá minimizar erros de transação.

    • Por exemplo, para códigos postais dos EUA, verifique se o campo é inteiramente numérico e se tem um formato de 5 dígitos ou o formato de código postal CP+4.

  • Para evitar um impacto negativo na disponibilidade e fiabilidade do sistema FedEx:
    • Não execute testes de desempenho no ambiente de teste ou produção.
    • Implemente a lógica da codificação para impedir que a transação falhe repetidamente.
  • O limite foi definido para 1400 transações a cada 10 segundos. Se este limite for atingido nos primeiros segundos, o código de erro HTTP 429 Too many requests (Demasiados pedidos) será devolvido e as transações serão restringidas até o período de 10 segundos ser atingido. As transações serão então retomadas.

    • Por exemplo, se recebermos 1400 pedidos nos primeiros 4 segundos, será devolvido o código de erro HTTP 429 Too many requests - "We have received too many requests in a short duration. Please wait a while to try again." (Foram recebidos demasiados pedidos num curto período. Aguarde e tente novamente.) As transações serão restringidas durante os 6 segundos seguintes e, após esse período, novamente retomadas.

  • Não codifique regras empresariais como tipos de serviço, tipos de volume, limites de peso, entre outras, para expedições, uma vez que estão sujeitas a alterações.
  • Para além disso, para garantir flexibilidade e preparação para o futuro, recomendamos que evite a codificação de valores de enumerações específicos em repostas de API, pois podem mudar ao longo do tempo. Implemente uma lógica que lide de forma dinâmica com valores novos ou inesperados.

Processamento de erros

Cada resposta da API irá conter um código de estado HTTP e carga paga de resposta. Algumas respostas serão acompanhadas por um erro, aviso ou nota, conforme aplicável. Os aviso e notas não são indicações de uma falha, mas a mensagem de aviso ou erro deve ser registada e examinada. O processamento adequado de erros irá garantir que a integração com a FedEx decorre de forma eficaz e pode ajudar a evitar interrupções.

Códigos de estado HTTP

200 OK 
Your request was processed successfully (O pedido foi processado com sucesso). Trata-se de uma resposta padrão para pedidos HTTP executados com sucesso.

  • Nota: a resposta da API pode conter notas e avisos que fornecem conteúdos informativos. Certifique-se de que regista e analisa as mensagens.

400 Bad request
We received a bad request that we are unable to process (Pedido inválido – recebemos um pedido inválido que não é possível processar). Modifique o pedido e tente novamente.

  • Nota: analise o código e a mensagem de erro para corrigir o pedido e tente novamente. Codifique apenas para códigos de erro e não mensagens de erro, uma vez que as mensagens estão sujeitas a alterações de forma dinâmica.

401 Unauthorized
We could not authenticate your credentials (Não autorizado – não foi possível autenticar as suas credenciais). Certifique-se de que verifica as suas chaves de API e tente novamente.

403 Forbidden
We could not authorize your credentials (Proibido – não foi possível autorizar as suas credenciais). Verifique as permissões e tente novamente.

404 Not found
The resource you requested is no longer available (Não encontrado – o recurso que pediu já não está disponível). Modifique o pedido e tente novamente.

405 Method not allowed
We received a requested method that is not supported (Método não permitido – recebemos um método de pedido que não é suportado). Apenas deve utilizar os métodos fornecidos para cada ponto final.

Por exemplo, para criar uma expedição, tem de utilizar o método POST conforme descrito na documentação da API.

409 Conflict
{provide reason of conflict} (Conflito). Modifique o pedido e tente novamente.

415 Unsupported media type
We do not support the content type in your request (Tipo de multimédia não suportado – não suportamos o tipo de conteúdo no seu pedido). Modifique o formato e tente novamente.

422 Unprocessable entity
We understood the format of your request, but we were unable to process the entity (Entidade não processável – o formato do pedido foi compreendido, mas não foi possível processar a entidade). Modifique o pedido e tente novamente.

429 Too many requests
We have received too many requests in a short duration (Demasiados pedidos – demasiados pedidos recebidos num curto período). Certifique-se de que revê as Quotas de transação e limites de tarifas.

500 Failure
We encountered an unexpected error and are working to resolve the issue (Falha – foi encontrado um erro inesperado e estamos a trabalhar para resolver o problema). Lamentamos qualquer inconveniência. Verifique mais tarde e esteja atento às comunicações da FedEx.

503 Service unavailable
The service is currently unavailable, and we are working to resolve the issue (Serviço indisponível – o serviço está atualmente indisponível e estamos a trabalhar para resolver o problema). Lamentamos qualquer inconveniência. Verifique mais tarde e esteja atento às comunicações da FedEx.

Tarifa

  • Existem duas formas de obter uma cotação de tarifa:
    • Tarifa para um serviceType específico: os resultados serão filtrados pelo valor de serviceType indicado. Isto irá diminuir o tamanho da resposta e reduzir o tempo de resposta da transação.

      Por exemplo: STANDARD_OVERNIGHT

    • Loja de tarifas: se não for indicado nenhum serviceType, todos os serviços aplicáveis e tarifas correspondentes serão devolvidas.
  • Utilize a API de Disponibilidade de Serviços para determinar os serviços, as opções de volumes e os serviços especiais que estão disponíveis para um determinado par origem-destino e passe o serviceType e a opção de volume no pedido de Tarifa.

    Por exemplo, STANDARD_OVERNIGHT (entre outros) não está disponível entre todos os códigos postais.

  • Para que um serviço especial seja aplicado numa expedição, o tipo de serviço especial e os respetivos detalhes têm de ser incluídos. 
    • Nota: alguns serviços especiais não têm detalhes.
  • Consulte a Documentação da API de Tarifas.

Expedir

  • Utilize a API de Disponibilidade de Serviços para determinar os serviços que estão disponíveis para um determinado par origem-destino e passe o serviceType e a opção de volume no pedido de Expedição.
  • Para que um serviço especial seja aplicado numa expedição, o tipo de serviço especial e os respetivos detalhes têm de ser incluídos.
    • Nota: alguns serviços especiais não têm detalhes.
  • Realize o fecho do FedEx Ground no final do dia de expedições antes da recolha da expedição.
  • Consulte a documentação da API de Expedição.

Rastrear

  • Limite a quantidade de números de rastreio num único pedido de rastreio para 30. Isto irá diminuir o tamanho da resposta e reduzir o tempo de resposta da transação.
  • Limite o número de vezes que um volume é rastreado de acordo com a frequência necessária para as necessidades de negócio.
  • Para o rastreamento de lotes, remova os volumes que tenham devolvido o estado de rastreio "entregue" do lote.
  • A FedEx reutiliza números de rastreio. Para a melhor experiência forneça o intervalo de datas para evitar resultados duplicados.
  • Consulte a Documentação de Visibilidade integrada básica.

Validação de Endereços

  • A FedEx fornece a Validação de Endereços como sugestão e não determinação final. O utilizador final tem de determinar se é possível utilizar um endereço a partir dos dados fornecidos e das necessidades do negócio. Tem de ser implementado um processo para endereços que não podem ser validados, de forma a permitir o processamento das encomendas.
  • Para garantir uma melhor experiência de expedição, não torne o processo de expedição dependente de serviços opcionais como a Validação de Endereços.

    • Por exemplo, se a API da Validação de Endereços estiver indisponível no momento da entrada ou expedição da encomenda, deve ser implementada uma contingência para concluir a expedição.

  • Consulte a documentação da API da Validação de Endereços.

Pesquisa de Estações FedEx

  • Limite a sua pesquisa ao fornecer atributos específicos (ou seja, tipo de localização, serviços oferecidos, etc.) para obter opções de localização adequadas e um tempo de resposta mais rápido.
  • Consulte a Documentação da API de Pesquisa de Estações FedEx.

Pedido de Recolha

  • Não defina uma hora a que está pronto no passado, uma data no passado ou uma data demasiado longínqua no futuro para agendar uma recolha.
  • Não são permitidas recolhas anónimas.
  • Consulte a Documentação da API do Pedido de Recolha.

Disponibilidade de Serviços

  • Para obter resultados de várias empresas subsidiárias como a FedEx Express (FDXE), FedEx Ground (FDXG), FedEx Freight (FXFR) e FedEx Ground® Economy , omita o elemento carrierCodes ou envie pedidos de disponibilidade de serviços em separado, uma vez que os códigos de várias transportadoras não podem ser especificados.
  • Certifique-se de que tem a pré-aprovação para paletes individuais de 68 kg ou mais e paletes que excedam 998 kg.
  • Se especificar SATURDAY_DELIVERY para opções variáveis, obterá as opções de entrega ao Sábado e as opções habituais para todos os serviços nos quais a entrega ao Sábado é uma opção. Não especifique SATURDAY_DELIVERY para serviços especiais ou apenas serão devolvidas as opções de entrega ao Sábado aplicáveis.
  • Consulte a Documentação da API de Disponibilidade de Serviços.

Apoio ao cliente

Se tiver alguma questão ou precisar de assistência, estamos aqui para ajudar! Aceda à nossa página de Apoio para obter recursos e informações sobre como entrar em contacto connosco.