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.

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.
  • Consulte a Documentação da API de Rastreio.

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.