Melhores práticas da integração de APIs da FedEx

Este é um guia de referência rápida para ajudar os consumidores de APIs a entender como melhorar a experiência de integração com a FedEx e garantir a qualidade da solução integrada em termos de design, velocidade e segurança.

Para realizar a integração eficiente com as APIs da FedEx, os desenvolvedores devem seguir essas melhores práticas:

URIs de API

• Há URIs de API diferentes para teste e produção. 
• Os desenvolvedores devem usar as URIs de teste para desenvolver e testar a integração, e a URI de produção para produção.

Lista de URIs de API:

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

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

Gerenciamento de credenciais

• Chave da API e chave secreta

• A chave da API e a chave secreta são usadas para identificar seu aplicativo e precisam ser usadas na solicitação de um token OAuth.

1. A chave da API e a chave secreta precisam ser tratadas com muita segurança. Não distribua a chave da API e a chave secreta por e-mail ou por código distribuído incluindo JavaScript de cliente.
2. Seu aplicativo ficará comprometido se a chave da API ou a chave secreta forem roubadas. Se suspeitar que suas credenciais foram roubadas ou estão comprometidas, recrie imediatamente a chave secreta.
3. Evite registrar informações confidenciais como a chave secreta.

• Não programe a chave da API e a chave secreta no seu código.
• O aplicativo deve poder atualizar dinamicamente a chave da API e a chave secreta.
• As credenciais do cliente devem ser armazenadas em um cofre ou outro local seguro para que não sejam comprometidas.

• Token OAuth

• O token de acesso deve ser armazenado apenas no servidor do aplicativo web e não deve ser exposto ao navegador.
• Não codifique o token nos seus aplicativos.
• Proteja os tokens de acesso para evitar que sejam comprometidos.
• Evite fazer múltiplas chamadas à API do token OAuth para um novo token de acesso. É recomendado armazenar o token de acesso em cache até que o código de erro de HTTP 401 seja observado. Regenere o token OAuth em qualquer momento.
• Não exponha o token ao usuário final do aplicativo.
• Use HTTPS para qualquer transação da API.

Práticas de codificação

• Para manter a conformidade com o protocolo de comunicação de criptografia de dados mais recente e seguro, é recomendado usar a versão 1.2 ou superior do protocolo de Segurança de Camada de Transporte (TLS).
• Lembre-se de definir os cabeçalhos de API necessários para cada solicitação de API. Você encontrará as informações de cabeçalho sob cada página de documentação da API. 
• O "Content-Type" no HTTP POST deve ser "application/json".
• Consulte o exemplo de código para começar em cada API. Cada endpoint de API é acompanhado de vários exemplos para ajudar você a entender os elementos e formatos necessários, além de outros detalhes.
• Quando os usuários ou desenvolvedores enviam muitos decimais em seus valores, podem ocorrer erros inesperados. Para peso e valor/quantia em moeda, são permitidas apenas duas casas decimais. Dimensões, como comprimento, largura e altura, não usam decimais.

Exemplo: peso: 45,26; valor/quantia em moeda: 100,52; comprimento: 10; largura: 25; altura: 15.

• Evite enviar elementos vazios.

Exemplo: “Streetlines”:””

• Envie apenas os dados necessários para o processamento da solicitação.

Por exemplo, em uma remessa dentro dos EUA, evite enviar a fatura comercial e dados da mercadoria que podem só ser necessários em remessas internacionais.

• Ao escrever o código, determine qual será a reação se um elemento de resposta não necessário, como taxa, não for retornado. Avalie a resposta da transação a elementos não encontrados antes de usar os dados.

Por exemplo, é possível enviar um pacote se a taxa não for funcional. Teste a resposta da transação a elementos não encontrados antes de usar os dados.

• Em geral, evite dependências rígidas na integração de APIs da FedEx quando aplicável.
• Para reduzir a latência e obter resultados precisos, use os seguintes recursos:
  
  • Filtro - use esse recurso para restringir a pesquisa a parâmetros que correspondem ao que está buscando.
  • Classificação - use esse recurso para classificar os resultados por um certo parâmetro em ordem crescente ou decrescente.
• Valide a presença de dados nos campos obrigatórios – como código postal do destinatário e peso do pacote – antes de enviar a transação. Verifique se os dados são apropriados ao campo em questão. Isso minimizará erros de transação.
  

Por exemplo, para códigos postais nos EUA, verifique se o campo é completamente numérico e está no formato de 5 dígitos ou no formato de CEP+4 dígitos.

• Para evitar impacto negativo na disponibilidade e confiabilidade do sistema FedEx:
  
  • Não faça testes de desempenho no ambiente de teste ou de produção.
  • Implemente uma lógica de codificação para evitar que a mesma transação falhe repetidamente.
• O controle de limite está definido como 1400 transações em 10 segundos. Se esse limite for alcançado nos primeiros poucos segundos, o código de erro HTTP 429 Excesso de solicitações será devolvido e as transações serão restringidas até completar os 10 segundos, quando serão retomadas.
  

Por exemplo, se recebermos 1400 solicitações nos primeiros quatro segundos, o código de erro HTTP 429 Excesso de solicitações - "Recebemos um excesso de solicitações em um período curto. Aguarde alguns segundos antes de tentar novamente." será retornado e as transações serão restringidas pelos próximos seis segundos, quando serão retomadas.

• Não codifique regras de negócios como tipos de serviço, tipos de pacote, limites de peso etc. para remessas, pois elas podem mudar.

Tratamento de erros

Cada resposta de API conterá um código de status HTTP e uma carga útil de resposta. Algumas respostas serão acompanhadas por um erro, um aviso ou uma observação, como aplicável. Avisos e observações não são indicações de falha, mas mensagens de erro ou de aviso devem ser registradas e examinadas. O tratamento apropriado de erros garantirá o funcionamento correto da sua integração com a FedEx e pode ajudar a evitar quebras.

Códigos de status HTTP

Tarifa

• Há duas maneiras de obter uma cotação de tarifa:
  
  • Tarifa para um serviceType específico - Os resultados serão filtrados pelo valor do serviceType indicado. Isso reduzirá o tamanho da resposta e o tempo de resposta da transação.
    

    Exemplo: STANDARD_OVERNIGHT

  • Dados de tarifa – se nenhum serviceType for indicado, todos os serviços aplicáveis e as tarifas correspondentes serão retornadas.
• Use a API de disponibilidade de serviço para determinar quais serviços, opções de pacotes e serviços especiais estão disponíveis para um par específico de origem e destino, e passe o serviceType e a opção de pacote na solicitação 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 a uma remessa, será necessário incluir o tipo de serviço especial e seus detalhes. 
  
  • Observação: alguns serviços especiais não têm dados detalhados.
• Consulte a documentação da API de tarifas.

Enviar

• Use a API de disponibilidade de serviço para determinar quais serviços estão disponíveis para um par específico de origem e destino, e passe o serviceType e a opção de pacote na solicitação de remessa.
• Para que um serviço especial seja aplicado a uma remessa, será necessário incluir o tipo de serviço especial e seus detalhes.
  
  • Observação: alguns serviços especiais não têm dados detalhados.
• Realize o fechamento do FedEx Ground ao final do dia de remessa antes que a remessa seja coletada.
  
• Consulte a documentação da API de remessa.
  

Rastrear

• Limite a quantidade de números de rastreamento em uma solicitação de rastreamento único a 30. Isso reduzirá o tamanho da resposta e o tempo de resposta da transação.
• Limite o número de vezes que um pacote pode ser rastreado de acordo com as necessidades dos negócios.
• Para realizar rastreamento em lote, remova quaisquer pacotes que tenham retornado um status de rastreamento de "entregue" do lote.
• Consulte a documentação da API de rastreamento.

Validação de endereço

• A FedEx fornece a validação de endereço como uma sugestão e não como uma determinação final. O usuário final precisa decidir se um endereço pode ser utilizado a partir dos dados fornecidos e das suas necessidades de negócios. Deve haver um processo implementado para lidar com endereços que não podem ser validados de forma que os pedidos possam ser processados.
• Para garantir uma melhor experiência de envio, não torne esse processo dependente de serviços opcionais como a validação de endereço.

Por exemplo, se a API de validação de endereço não estiver disponível no momento da entrada do pedido ou da remessa, deve haver uma solução de contingência para concluir a remessa.

• Consulte a documentação da API de validação de endereço.
  

Pesquisa de localidades FedEx

• Restrinja sua pesquisa fornecendo atributos específicos (por exemplo, tipo de localidade, serviços oferecidos etc.) para obter opções de localidades adequadas e menor tempo de resposta.
• Visualize a documentação da API de pesquisa de localidades FedEx.
  

Solicitação de coleta

• Não insira uma hora ou data no passado, ou uma data que muito distante no futuro, para indicar quando a remessa estará pronta ao agendar uma coleta.
• Coletas anônimas não são permitidas.
  
• Consulte a documentação da API de solicitação de coleta.
  

Disponibilidade de serviços

• Para obter resultados de várias empresas operadoras, como FedEx Express (FDXE), FedEx Ground (FDXG), FedEx Freight (FXFR) e FedEx Ground® Economy, omita o elemento carrierCodes ou envie solicitações separadas de disponibilidade de serviço já que não é possível especificar múltiplos códigos de transportador.
• Certifique-se de ter aprovação para estrados individuais de 68,5 kg ou mais e para estrados com mais de 998 kg.
  
• Se especificar SATURDAY_DELIVERY como opção variável, você obterá tanto opções de entrega no sábado como normais para todos os serviços com opção para entrega nos sábados. Não especifique SATURDAY_DELIVERY para serviços especiais, ou serão retornadas apenas as opções de entrega nos sábados aplicáveis.
• Consulte a documentação da API de disponibilidade de serviços.

Suporte ao cliente

Se você tiver qualquer dúvida ou precisar de ajuda, estamos aqui para ajudá-lo! Acesse nossa página de Suporte para consultar nossos recursos e nossas informações de contato.