Mejores prácticas de integración de las API de FedEx

Esta es una guía de referencia rápida destinada a ayudar a los consumidores de una interfaz de programación de aplicaciones (API) a conocer formas de mejorar la experiencia de integración con FedEx y garantizar la calidad de la solución de integración en términos de diseño, velocidad y seguridad.

Los desarrolladores deben seguir estas mejores prácticas de integración para integrarse de manera eficiente con las API de FedEx:

URL de API

• Hay URL de API individuales para pruebas y para producción. 
• Los desarrolladores deben usar las URL de prueba para evaluar el desarrollo e integración, y las URL de producción para la producción.

Se enumeran las URL de API:

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

Producción: https://apis.fedex.com

Gestión de credenciales

• Clave de API y clave secreta

• Su clave de API y clave secreta se usan para identificar su aplicación y deben usarse cuando se solicite una señal de autorización abierta (OAuth).

1. Su clave de API y clave secreta deben tratarse de una manera muy segura. No comparta la clave de API ni la clave secreta por correo electrónico o código distribuido, incluido JavaScript del lado del cliente.
2. Su aplicación se verá comprometida si roban su clave de API o clave secreta. Si sospecha que robaron o se vieron comprometidas sus credenciales, vuelva a crear la clave secreta de inmediato.
3. Evite ingresar información sensible como la clave secreta.

• No codifique la clave de API ni la clave secreta en su código.
• Su aplicación debe tener la capacidad dinámica de actualizar la clave de API y la clave secreta.
• Las credenciales del cliente deben almacenarse en una bóveda o un lugar seguro para que evitar que se vean comprometidas.

• Señal de OAuth

• La señal de acceso solo debe almacenarse en el servidor de la aplicación web y no debe exponerse al navegador.
• No codifique la señal de sus aplicaciones.
• Asegure las señales de acceso para evitar que se vean comprometidas.
• Evite hacer múltiples llamadas a la API de la señal de OAuth para obtener una nueva señal de acceso. Se recomienda almacenar en caché la señal de acceso hasta que se observe el error de código HTTP 401. En ese momento vuelva a generar la señal de OAuth.
• No exponga la señal al usuario final ni a la aplicación.
• Use HTTPS para cualquier transacción de API.

Prácticas de codificación

• Para mantener el cumplimiento del protocolo de comunicación de cifrado de datos más reciente y seguro, se recomienda utilizar la versión 1.2 o una versión superior del protocolo de Seguridad de la capa de transporte (TLS).
• No olvide establecer los encabezados de API correctos necesarios para cada solicitud de API. Encontrará la información del encabezado en la página de documentación de cada API. 
• El «Tipo de contenido» en HTTP POST debe ser «application/json».
• Consulte el código de muestra para comenzar con cada API. Cada extremo de API está acompañado de varias muestras que le ayudarán a comprender los elementos, formatos y otros detalles requeridos.
• Cuando los usuarios o desarrolladores envían muchos decimales en sus valores, se pueden producir errores extraños. Para el peso y valor monetario/monto solo se permiten dos decimales explícitos. Las dimensiones, como el largo, el ancho y la altura, no admiten decimales.

Ejemplo: Peso: 45,26; valor monetario/monto: 100,52; longitud: 10; ancho: 25; altura: 15.

• Evite enviar elementos vacíos.

Ejemplo: «Líneas de calle»: «»

• Solo envíe los datos necesarios para procesar la solicitud.

Por ejemplo, para un envío nacional de EE. UU., evite enviar el recibo comercial y los datos de la mercancía que podrían ser necesarios solo para envíos internacionales.

• Al hacer un desarrollo, determine cómo reaccionar si no se devuelve un elemento de respuesta no requerido, como una tarifa. Evalúe la respuesta de la transacción para elementos faltantes antes de usar los datos.

Por ejemplo, es posible enviar un paquete si la estimación de tarifas no es funcional. Pruebe la respuesta de la transacción para detectar elementos faltantes antes de usar los datos.

• En general, evite las dependencias fuertes en la integración de las API de FedEx cuando corresponda.
• Con el fin de reducir la latencia y obtener resultados precisos, se debe utilizar lo siguiente:
  
  • Filtrado: Use esto para reducir la búsqueda con los parámetros que está buscando.
  • Clasificación: Use esto para ordenar los resultados con un parámetro determinado en orden ascendente o descendente.
• Valide que los campos obligatorios, como el código postal del destinatario y el peso del paquete, tengan datos antes de enviar la transacción. Validar los datos es apropiado para el campo en cuestión. Esto minimizará los errores de transacción.
  

Por ejemplo, para los códigos postales de EE. UU., verifique que todo el campo sea numérico y que tenga la forma de un código postal de 5 dígitos o un formato de código postal +4.

• Para evitar impactos adversos en la disponibilidad y la confiabilidad del sistema de FedEx:
  
  • No ejecute una prueba de rendimiento en el entorno de pruebas o producción.
  • Implemente una lógica de codificación para evitar que la misma transacción falle repetidamente.
• El límite de aceleración se establece en 750 transacciones durante 10 segundos. Si se alcanza este límite en los primeros segundos, el código de error HTTP 429 Demasiadas solicitudes aparecerá y las transacciones se restringirán hasta que pasen 10 segundos; después, las transacciones se reanudarán de nuevo.
  

Por ejemplo, si recibimos 750 solicitudes en los primeros cuatro segundos, aparecerá un código de error HTTP 429 Demasiadas solicitudes: «Recibimos demasiadas solicitudes en poco tiempo. Espera y vuelve a intentarlo.» aparecerá y las transacciones se restringirán durante los próximos seis segundos y luego se reanudarán nuevamente.

• No codifique reglas comerciales como tipos de servicios, tipos de paquetes, límites de peso, etc. para los envíos, ya que están sujetos a cambios.

Manejo de errores

La respuesta de cada API contendrá un código de estado HTTP y una carga útil de respuesta. Algunas respuestas irán acompañadas de un error, advertencia o nota, según corresponda. Las advertencias y notas no son indicaciones de una falla; sin embargo, el mensaje de error o advertencia debe registrarse y examinarse. El manejo adecuado de los errores asegurará que su integración con FedEx se realice sin problemas y podría ayudar a evitar roturas.

Códigos de estado HTTP

Tarifa

• Existen dos formas de obtener una tarifa estimada:
  
  • Tarifa para un serviceType específico: Los resultados se filtrarán por el valor del serviceType indicado. Esto disminuirá el tamaño de la respuesta y reducirá el tiempo de respuesta de la transacción.
    

    Ejemplo: STANDARD_OVERNIGHT

  • Comparar tarifas: Si no se indica el tipo de servicio, se mostrarán todos los servicios aplicables y las tarifas correspondientes.
• Use la API de disponibilidad de servicios para determinar qué servicios, opciones de embalaje y servicios especiales están disponibles para un par de origen/destino determinado, y pase el serviceType y la opción de paquete a la solicitud de tarifa.
  

  Por ejemplo, STANDARD_OVERNIGHT (entre otros) no está disponible en todos los códigos postales.

• Para que se aplique un servicio especial a un envío, se debe incluir el tipo de servicio especial y sus detalles. 
  
  • Nota: Algunos servicios especiales no tienen detalles.
• Consulte la Documentación de la API de tarifas.

Envío

• Use la API de disponibilidad de servicios para determinar qué servicios están disponibles para un par de origen/destino determinado y pase el tipo de servicio y la opción de paquete a la solicitud de envío.
• Para que se aplique un servicio especial a un envío, se debe incluir el tipo de servicio especial y sus detalles.
  
  • Nota: Algunos servicios especiales no tienen detalles.
• Realice el cierre de FedEx Ground al final del día de envío antes de que se recolecte el envío.
  
• Consulte la Documentación de la API de envío.
  

Rastrear

• Limite la cantidad de números de rastreo en una sola solicitud a 30. Esto disminuirá el tamaño de la respuesta y reducirá el tiempo de respuesta de la transacción.
• Limite la cantidad de veces que se rastrea un paquete a lo que sea necesario para las necesidades del negocio.
• Para el rastreo por lotes, elimine los paquetes que tengan un estado de rastreo de «entregado» del lote.
• Consulte la documentación de la API de rastreo.

Validación de la dirección

• FedEx proporciona la validación de la dirección como una sugerencia y no como una determinación final. El usuario final debe tomar la decisión final de si una dirección puede utilizarse a partir de los datos proporcionados y sus necesidades comerciales. Debe existir un proceso para manejar las direcciones que no se puedan validar para que los pedidos puedan procesarse.
• Para garantizar una mejor experiencia de envío, no haga que el proceso de envío dependa de servicios opcionales como la validación de la dirección.

Por ejemplo, si la API de validación de la dirección no está disponible en el momento de ingresar o enviar el pedido, debe existir una contingencia para completar el envío.

• Consulte la Documentación de la API de validación de la dirección.
  

Búsqueda de oficinas de FedEx

• Limite su búsqueda proporcionando atributos específicos (es decir, tipo de ubicación, servicios ofrecidos, etc.) para obtener opciones de ubicaciones adecuadas y un tiempo de respuesta más rápido.
• Consulta la Documentación de la API de búsqueda de oficinas de FedEx.
  

Solicitud de recolección

• No ingrese una hora en que estará listo el paquete que ya haya pasado, una fecha pasada ni una fecha que esté demasiado lejos en el futuro para programar una recolección.
• No se permiten las recolecciones anónimas.
  
• Consulte la Documentación de la API de solicitud de recolección.
  

Disponibilidad de los servicios

• Para obtener resultados para múltiples compañías operativas como FedEx Express (FDXE), FedEx Ground (FDXG), FedEx Freight (FXFR) y FedEx Ground® Economy, omite el elemento carrierCodes o envía solicitudes de disponibilidad de servicios por separado, ya que no se pueden especificar múltiples códigos de transportista.
• Asegúrese de contar con la aprobación previa para tarimas individuales de 68,49 kg o más y tarimas que excedan los 997,90 kg.
  
• Si especifica SATURDAY_DELIVERY para opciones variables, obtendrá las opciones de entrega en sábado y las opciones regulares para todos los servicios donde la entrega en sábado es una opción. No especifique SATURDAY_DELIVERY para servicios especiales, o solo mostrará las opciones de entrega en sábado aplicables.
• Consulte la Documentación de la API de disponibilidad de servicios.

Soporte al cliente

¡Estamos aquí para apoyarlo si tiene preguntas o necesita ayuda! Visite nuestra página de Soporte para encontrar recursos e información sobre las formas de comunicarse con nosotros.