Prácticas recomendadas de integración de las API de FedEx

Esta es una guía de referencia rápida diseñada para ayudar a que los usuarios de las API comprendan las formas de mejorar la experiencia de integración con FedEx y garantizar la calidad de la solución de integración en lo que respecta a diseño, velocidad y seguridad.

Para garantizar una integración eficaz con las API de FedEx, los desarrolladores deben seguir estas prácticas recomendadas:

URI de las API

• Se usan URI de API diferentes para la prueba y la producción. 
• Los desarrolladores deben usar los URI de prueba para pruebas de desarrollo e integración, y el URI de producción para producción.

A continuación se enumeran los URI de las API:

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

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

Gestión de credenciales

• Clave de API y Clave secreta

• La clave de API y la clave secreta se utilizan para identificar su aplicación y se tienen que utilizar en una solicitud de token OAuth.

1. Se deben extremar las medidas de seguridad en torno a la clave de API y la clave secreta. No envíe la clave API ni la clave secreta por correo electrónico o código distribuido incluyendo JavaScript de cliente.
2. Su aplicación estará en peligro si alguien le roba su clave de API o clave secreta. Si sospecha que sus credenciales han podido ser robadas o están en peligro, vuelva a crear una clave secreta de inmediato.
3. Evite registrar información confidencial como la clave secreta.

• No codifique la clave de API ni la clave secreta en su código.
• Su aplicación debe poder actualizar dinámicamente la clave de API y la clave secreta.
• Las credenciales del cliente se deben guardar en una caja fuerte o en un lugar seguro para evitar su exposición.

• Token OAuth

• El token de acceso se debe guardar en el servidor de aplicación web únicamente y no se debe exponer en el navegador.
• No codifique el token en sus aplicaciones.
• Proteja los tokens de acceso para no ponerlos en peligro.
• Evite realizar varias llamadas a la API de token OAuth para un nuevo token de acceso. Se recomienda almacenar en el caché el token de acceso hasta que aparezca el código de error HTTP 401. Vuelva a generar el token OAuth en ese momento.
• No exponga el token ante el usuario final o la aplicación.
• Utilice HTTPS para todas las transacciones de API.

Prácticas de codificación

• Con el fin de mantener el cumplimiento con el protocolo de cifrado de datos más reciente y seguro, se recomienda usar la versión 1.2 o superior de Seguridad de la capa de transporte (TLS).
• No se olvide de definir los encabezados API adecuados necesarios para cada solicitud de API. Encontrará la información del encabezado en cada página de documentación de API. 
• El ’Content-Type’ en HTTP POST debe ser ‘application/json’.
• Consulte el código de ejemplo para empezar a usar cada API. Cada punto de conexión API se acompaña de varios ejemplos que le ayudarán a comprender los elementos, los formatos y otros detalles necesarios.
• Si los usuarios o los desarrolladores envían valores con muchos decimales, podrían surgir errores ocasionales. En el caso de valores o cantidades de peso y divisa, únicamente se permiten dos espacios para decimales explícitos. Dimensiones, como longitud, anchura y altura, no admiten decimales.

Ejemplo: Peso: 45,26; Valor o cantidad de divisa: 100,52; Longitud: 10; Anchura: 25; Altura: 15.

• Evite enviar elementos vacíos.

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

• Envíe únicamente los datos necesarios para procesar la solicitud.

Por ejemplo, para un envío nacional dentro de EE. UU., evite enviar la factura comercial y datos de mercancía que tal vez solo se necesiten para envíos internacionales.

• En la fase de desarrollo, determine cómo reaccionar si un elemento de respuesta no necesario, como una tarifa, no se devuelve. Evalúe la respuesta de transacción para elementos que faltan antes de usar datos.

Por ejemplo, es posible enviar un paquete si la tarifa no es funcional. Pruebe la respuesta de transacción para elementos que faltan antes de usar datos.

• En términos generales, evite una gran dependencia de la integración de la API de FedEx cuando así proceda.
• A fin de reducir la latencia y obtener resultados precisos, se tiene que utilizar lo siguiente:
  
  • Filtro: utilice esta función para acotar la búsqueda con los parámetros que busque.
  • Clasificación: utilice esta función para clasificar los resultados en función de un determinado parámetro, por orden ascendente o descendente.
• Compruebe si los campos obligatorios, como el código postal del destinatario y el peso del paquete, tienen los datos pertinentes antes de enviar la transacción. Verifique si los datos son adecuados para el campo en cuestión. De este modo, minimizará los errores de transacción.
  

Por ejemplo, en el caso de los códigos postales de EE. UU., verifique si el campo es totalmente numérico y si sigue el formato de 5 dígitos o el de ZIP+4.

• Para evitar efectos adversos en la fiabilidad y la disponibilidad del sistema de FedEx:
  
  • No realice pruebas de rendimiento en el entorno de pruebas o producción.
  • Aplique la lógica de codificación para evitar que la misma transacción falle repetidamente.
• El máximo de limitaciones se ha configurado en 1400 transacciones en 10 segundos. Si se llega a este límite en los primeros segundos, aparecerá el código de error HTTP 429 Demasiadas solicitudes y las transacciones se restringirán hasta alcanzar los 10 segundos; a continuación, las transacciones se reanudarán.
  

Por ejemplo, si recibimos 1400 solicitudes en los primeros cuatro segundos, aparecerá el código de error HTTP 429 Demasiadas solicitudes: «Hemos recibido demasiadas solicitudes en un breve periodo de tiempo. Espere unos instantes para volver a intentarlo». Después, las transacciones se restringirán durante los próximos seis segundos y, a continuación, se reanudarán.

• No codifique reglas de negocio como tipos de servicio, tipos de paquete, límites de peso, etc. en los envíos, pues están sujetas a cambios.

Gestión de errores

Cada respuesta de API contendrá un código de estado HTTP y una carga de respuesta. Algunas respuestas se acompañarán de un error, una advertencia o una nota, según proceda. Las advertencias y las notas no son indicaciones de fallos; sin embargo, el mensaje de error o advertencia se deberá registrar y analizar. Una correcta gestión de los errores garantizará el perfecto funcionamiento de su integración con FedEx y podría ayudar a evitar los errores.

Códigos de estado HTTP

Tarifa

• Hay dos formas de obtener una cotización de tarifa:
  
  • Tarifa para un tipo de servicio concreto: los resultados se filtrarán por el valor serviceType indicado. Así se reducirá el tamaño de la respuesta y el tiempo de la respuesta de la transacción.
    

    Ejemplo: STANDARD_OVERNIGHT

  • Tienda de tarifa: si no se indica un serviceType, entonces se devolverán todos los servicios aplicables y las tarifas correspondientes.
• Utilice la API de disponibilidad de servicios para determinar qué servicios, opciones de paquete y servicios especiales están disponibles para un par destino-origen determinado, y pasar el serviceType y la opción de paquete a la solicitud de tarifa.
  

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

• Para que se aplique un servicio especial a un envío, tendrá que incluir el tipo de servicio especial y sus detalles. 
  
  • Nota: Algunos servicios especiales carecen de detalles.
• Consulte la documentación de la API de tarifa.

Enviar

• Utilice la API de disponibilidad de servicios para determinar qué servicios están disponibles para un par destino-origen determinado y pasar el tipo de servicio y la opción de paquete en la solicitud de envío.
  
• Para que se aplique un servicio especial a un envío, tendrá que incluir el tipo de servicio especial y sus detalles.
  
  • Nota: Algunos servicios especiales carecen de detalles.
• Realice el cierre de FedEx Ground al final del día del envío antes de su recogida.
  
• Consulte la documentación de la API de envío.
  

Seguimiento

• Limite a 30 la cantidad de números de seguimiento de una sola solicitud de seguimiento. Así se reducirá el tamaño de la respuesta y el tiempo de la respuesta de la transacción.
  
• Limite a lo estrictamente necesario la cantidad de veces que un paquete se puede seguir para las necesidades comerciales.
• En el caso del seguimiento de lotes, elimine los paquetes que hayan devuelto un estado de seguimiento de “entregado” desde el lote.
• Consulte la documentación de la API de seguimiento.

Validación de direcciones

• FedEx proporciona Validación de direcciones como sugerencia y no como resolución definitiva. El usuario final tiene que tomar la decisión final de si se puede usar una dirección de los datos proporcionados y sus necesidades comerciales. Debe aplicarse un proceso para administrar las direcciones que no se pueden validar para que se puedan seguir procesando los pedidos.
• A fin de garantizar una mejor experiencia de envío, no vincule el proceso de envío a servicios opcionales como la Validación de direcciones.

Por ejemplo, si la API de validación de direcciones no está disponible en el momento de la introducción del pedido o el envío, se debe aplicar una medida para completar el envío.

• Consulte la documentación de la API de validación de direcciones.
  

Búsqueda de instalaciones de FedEx

• Restrinja su búsqueda proporcionando atributos específicos (por ejemplo, tipo de ubicación, servicios ofrecidos, etc.) para obtener opciones de ubicación adecuadas y un tiempo de respuesta más breve.
• Consulte la documentación de la API de búsqueda de instalaciones de FedEx.
  

Solicitud de recogida

• No introduzca una hora de paquete listo pasada, una fecha anterior o una fecha muy avanzada para programar una recogida.
• No se permiten las recogidas anónimas.
  
• Consulte la documentación de la API de solicitud de recogida.
  

Disponibilidad de servicios

• Para obtener resultados de varias compañías operativas como FedEx Express (FDXE), FedEx Ground (FDXG), FedEx Freight (FXFR) y FedEx Ground® Economy, omita el elemento carrierCodes o envíe solicitudes independientes de disponibilidad de servicios, puesto que no es posible especificar varios códigos de empresa de transporte.
• Asegúrese de tener una aprobación previa para plataformas individuales de 151 lb o más, y plataformas de más de 2200 lb.
  
• Si especifica SATURDAY_DELIVERY para opciones variables, obtendrá opciones de entrega en sábado y opciones estándar para todos los servicios en los que se ofrezca la opción de entrega en sábado. No especifique SATURDAY_DELIVERY para servicios especiales, pues solo se devolverán las opciones de entrega aplicables de entrega en sábado.
• Consulte la documentación de la API de disponibilidad de servicios.

Servicio de atención al cliente

Si tiene preguntas o necesita ayuda, estamos a su disposición. Acuda a nuestra página de Atención al cliente para ver recursos e información sobre formas de ponerse en contacto con nosotros.