API de seguimiento de Fedex: Cómo rastrear paquetes paso a paso

Para rastrear paquetes de FedEx mediante una aplicación, crea una cuenta de FedEx Developer, obtén las credenciales de la API, solicita un token de acceso OAuth, envía una solicitud de seguimiento y asigna la respuesta a tu flujo de trabajo de pedidos o envíos. La API de seguimiento de FedEx está destinada a sistemas de software que necesitan datos sobre el estado de los envíos, mientras que el sitio web de FedEx suele ser más rápido para comprobar manualmente un paquete.

Esta guía explica la secuencia de integración, la información que se debe validar, los errores comunes de implementación y una alternativa para las empresas que necesitan seguimiento de múltiples transportistas en lugar de una conectividad exclusiva con FedEx. Los campos exactos de las solicitudes, las reglas de autenticación, los entornos y la disponibilidad del servicio siempre deben confirmarse en la documentación vigente de FedEx antes de implementar en producción.

Elige primero el método de seguimiento adecuado

El mejor método depende de quién realizará la acción y de cuántos envíos deben supervisarse.

• Consulta puntual: Usa la página de seguimiento de FedEx cuando un cliente o agente de soporte solo necesite comprobar un envío individual.
• Aplicación interna: Usa la API de seguimiento de FedEx cuando un sistema de gestión de pedidos, una aplicación de almacén, un portal del cliente o una herramienta de soporte necesite datos de estado mediante programación.
• Operación con múltiples transportistas: Considera una plataforma de seguimiento cuando la empresa reciba envíos de FedEx y de otros transportistas y quiera una integración normalizada, un único modelo de estados o una sola experiencia de seguimiento para el cliente.

Una integración de API exclusiva de FedEx puede proporcionar control directo y ser adecuada para un sistema basado en envíos de FedEx. También significa que tu equipo debe gestionar por sí mismo la autenticación, los límites de solicitudes, los cambios en las respuestas, la lógica de estados específica del transportista, el manejo de errores y cualquier integración adicional con otros transportistas.

Qué necesitas antes de usar la API de seguimiento de FedEx

Prepara los siguientes elementos antes de escribir la integración:

• Una cuenta de FedEx Developer y acceso al portal para desarrolladores de FedEx.
• Las credenciales de API necesarias para el entorno de FedEx seleccionado. La documentación de FedEx puede referirse a credenciales como un ID de cliente y un secreto de cliente.
• Una relación de cuenta con FedEx u otra información de cuenta si la operación de API seleccionada lo requiere.
• Una ubicación segura en el servidor para las credenciales. No expongas el secreto de cliente en JavaScript del navegador, una aplicación móvil o un repositorio público.
• Al menos un identificador de envío válido para las pruebas, como un número de seguimiento de FedEx. Los datos de prueba deben representar los tipos de envío y servicios que procesará tu aplicación.
• Un plan para almacenar el último estado conocido, la marca de tiempo del evento, la información de ubicación y la hora de la última comprobación exitosa.

FedEx separa el acceso de desarrolladores, la autenticación, los entornos de API y los requisitos operativos. Iniciar sesión correctamente en el portal para desarrolladores no demuestra por sí mismo que una solicitud de producción esté lista. Consulta la documentación actual del producto para conocer los requisitos previos de la cuenta, los requisitos de aprobación, las URL de los entornos y cualquier restricción de uso.

Paso 1: Crea una aplicación en el portal para desarrolladores de FedEx

Comienza en el portal oficial FedEx Developer Portal e identifica el producto Track API. Crea o selecciona una aplicación y registra las credenciales proporcionadas para el entorno que pretendes utilizar. Mantén separadas las credenciales de desarrollo y producción.

En esta etapa, confirma cuatro detalles:

1. Qué producto de API contiene la operación de seguimiento que necesitas.
2. Qué URL base corresponde al entorno de pruebas o producción.
3. Qué método de autenticación y permisos, si corresponde, son necesarios.
4. Si la solicitud necesita un número de cuenta de FedEx u otro campo relacionado con la cuenta.

No copies una URL ni el nombre de un campo de un ejemplo de código antiguo sin comprobar la documentación actual. Las API de los transportistas pueden cambiar las versiones de los endpoints, las cabeceras obligatorias, las estructuras de respuesta o las reglas de incorporación.

Paso 2: Solicita un token de acceso OAuth

La autenticación de la API de FedEx utiliza normalmente las credenciales de cliente de OAuth 2.0. Tu aplicación envía sus credenciales de cliente al endpoint de autorización de FedEx y recibe un token de acceso de corta duración. Después, la aplicación envía ese token en la cabecera Authorization de la solicitud de seguimiento.

Un ejemplo simplificado de línea de comandos sería el siguiente:

curl -X POST "<FEDEX_OAUTH_URL>" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=<CLIENT_ID>" \
  -d "client_secret=<CLIENT_SECRET>"

Considera esto como un patrón de implementación, no como un sustituto de la documentación de autenticación vigente de FedEx. El código de producción debe leer el valor de expiración del token, almacenarlo en caché de forma segura y solicitar uno nuevo cuando expire o cuando la API devuelva un error de autenticación. Evita solicitar un token nuevo para cada número de seguimiento, salvo que los límites oficiales y tu patrón de tráfico lo hagan necesario.

Entre las medidas de seguridad útiles para la autenticación se incluyen:

• Almacenar los secretos en un gestor de secretos del servidor o en variables de entorno protegidas.
• No escribir nunca tokens de acceso ni secretos de cliente en los registros de la aplicación.
• Utilizar credenciales separadas para desarrollo y producción cuando la plataforma admita dicha separación.
• Devolver un error controlado al usuario cuando falle la autenticación; no exponer la respuesta sin procesar del transportista.
• Supervisar los fallos de tokens por separado de los fallos de números de seguimiento no válidos.

Paso 3: Construye la solicitud de seguimiento

Después de obtener un token válido, construye la solicitud descrita en la documentación actual de FedEx Track API. Por lo general, la solicitud identifica uno o más registros de envío y puede incluir opciones que afectan al nivel de detalle devuelto. Los nombres exactos de las propiedades JSON y los campos obligatorios deben proceder de la versión del endpoint de FedEx que estés utilizando.

Un patrón representativo de solicitud podría ser el siguiente:

curl -X POST "<FEDEX_TRACK_BASE_URL>/track/v1/trackingnumbers" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "trackingInfo": [
      {
        "trackingNumberInfo": {
          "trackingNumber": "<FEDEX_TRACKING_NUMBER>"
        }
      }
    ],
    "includeDetailedScans": true
  }'

La ruta del endpoint y los nombres de los campos anteriores deben comprobarse en la documentación activa de FedEx antes de usarlos. Algunas integraciones pueden necesitar una estructura de solicitud diferente, un número de cuenta, una consulta basada en una referencia u otra opción para los escaneos detallados. No supongas que un número de seguimiento perteneciente a otro transportista puede enviarse a un endpoint exclusivo de FedEx.

Paso 4: Analiza la respuesta y conviértela en campos empresariales

No transmitas la respuesta completa del transportista directamente a una página orientada al cliente. Primero, asígnala a un modelo interno estable. Un registro de envío práctico puede incluir:

• Transportista: FedEx.
• Identificador de seguimiento: El identificador enviado a la API.
• Estado actual: Tu estado normalizado, como etiqueta creada, en tránsito, en reparto, entregado, excepción o desconocido.
• Estado del transportista: El estado o código original de FedEx, conservado para soporte y depuración.
• Último evento: La descripción y la marca de tiempo del evento más reciente devuelto por FedEx.
• Entrega estimada: Almacénala solo cuando la respuesta la proporcione y muéstrala como una estimación, no como una garantía.
• Confirmación de entrega: Utiliza la respuesta del transportista para determinar si se ha informado de la entrega.
• Hora de la última comprobación: La marca de tiempo registrada por tu sistema, que es distinta de la hora del evento informada por FedEx.

La normalización de estados requiere criterio editorial y operativo. Por ejemplo, una excepción no debe mostrarse automáticamente como una entrega fallida, y un evento de etiqueta creada no significa necesariamente que el paquete esté desplazándose por la red. Conserva el evento original del transportista junto con tu estado normalizado para que el personal de soporte pueda investigar las diferencias.

Paso 5: Gestiona los errores y la información incompleta

Una integración de seguimiento en producción debe distinguir entre distintos tipos de fallos. Una solicitud mal formada, un token caducado, un número de seguimiento no válido, una interrupción temporal del transportista y una respuesta exitosa sin ningún evento útil no representan la misma condición.

Situación	Gestión recomendada
Fallo de autenticación	Actualiza las credenciales o la gestión del token y avisa al responsable de la integración si el problema continúa.
Solicitud no válida	Valida la carga útil, las cabeceras obligatorias, el formato del identificador y el entorno antes de volver a intentarlo.
Número de seguimiento no encontrado	Muestra un estado no resuelto o no disponible; no informes al cliente de que el paquete se ha perdido sin pruebas adicionales.
Tiempo de espera agotado o error temporal del servidor	Utiliza reintentos limitados con espera progresiva y conserva el último estado conocido.
Sin escaneo reciente	Muestra el último evento confirmado y su antigüedad en lugar de inventar una ubicación actual.

La lógica de reintentos debe ser conservadora. Las solicitudes repetidas pueden aumentar la carga, generar alertas innecesarias o entrar en conflicto con los límites de la API. Aplica tiempos de espera, espera exponencial, procesamiento idempotente y supervisión de fallos repetidos. Los límites exactos de frecuencia y los compromisos de servicio deben tomarse de tu acuerdo con FedEx o de la documentación actual, no suponerse a partir de una aplicación de ejemplo.

Paso 6: Programa las actualizaciones sin crear una mala experiencia para el cliente

La mayoría de los sistemas de envíos no necesitan solicitar un resultado nuevo cada pocos segundos. Utiliza una estrategia de actualización basada en el estado del envío. Un envío nuevo puede necesitar comprobaciones más frecuentes después de crear la etiqueta, mientras que normalmente un envío entregado debe dejar de consultarse. Una excepción puede requerir un flujo de trabajo de soporte independiente en lugar de consultas automatizadas más rápidas.

Al presentar los resultados a los clientes, incluye la hora del último evento del transportista y deja claro si la fecha de entrega es estimada. Si la API no está disponible temporalmente, conserva el último resultado verificado y explica que el estado no se ha actualizado. Esto es más útil que sustituir un estado conocido por un error genérico.

Paso 7: Prueba el flujo de trabajo completo

Prueba más que una respuesta exitosa. Un plan de pruebas realista debe cubrir:

• Un número de seguimiento válido con varios eventos de escaneo.
• Un envío recién creado con un historial de seguimiento limitado.
• Un envío entregado.
• Un envío con excepción o retraso, si hay datos de prueba representativos disponibles.
• Un número de seguimiento no válido o incompleto.
• Una credencial caducada o revocada.
• Un tiempo de espera agotado, una respuesta por límite de frecuencia y un error temporal del servidor.
• Eventos duplicados y eventos que llegan fuera de orden.
• Diferentes zonas horarias y transiciones al horario de verano.
• La ocultación de credenciales, tokens, datos personales y cargas útiles completas del transportista en los registros.

Antes de entrar en funcionamiento, compara tu estado normalizado con la página de seguimiento de FedEx usando una muestra controlada. Las dos vistas pueden no actualizarse exactamente al mismo tiempo, por lo que el objetivo es confirmar que tu analizador interpreta correctamente la respuesta y no convierte la falta de datos en una afirmación definitiva.

Cuándo una API de seguimiento de múltiples transportistas es más adecuada

Una integración directa con FedEx tiene sentido cuando FedEx es el transportista principal y tu equipo quiere encargarse de toda la lógica de la aplicación. Es menos eficiente cuando los pedidos pueden pasar por varios transportistas, marketplaces, operadores postales o servicios de entrega regionales. En esa situación, la empresa puede necesitar detección del transportista, un modelo de estados común, orquestación mediante webhooks o consultas, páginas de seguimiento con marca y una única vista de soporte.

17TRACK ofrece una API de seguimiento independiente y publica documentación para desarrolladores en api.17track.net. Puede evaluarse como una opción para múltiples transportistas cuando el requisito es más amplio que el seguimiento exclusivo de FedEx. La elección adecuada depende de los transportistas, países, nivel de detalle de los eventos, modelo de integración, condiciones comerciales y controles operativos que tu proyecto pueda verificar durante las pruebas. Un servicio de múltiples transportistas no elimina la necesidad de probar las excepciones específicas de cada transportista ni de validar la precisión y el momento de los eventos para tu propia combinación de envíos.

Lista de comprobación práctica para la implementación

• Confirma que el producto de API de FedEx coincide con el tipo de consulta que necesitas.
• Verifica el endpoint de autenticación actual, la URL base, el esquema de la solicitud y las cabeceras obligatorias.
• Mantén los secretos de cliente y los tokens de acceso en el servidor.
• Almacena en caché y actualiza los tokens OAuth de forma segura.
• Valida los identificadores de seguimiento antes de enviar las solicitudes.
• Almacena tanto el estado original del transportista como tu estado normalizado.
• Registra por separado la hora del evento del transportista y la hora de recuperación de tu sistema.
• Utiliza reintentos limitados y supervisa por separado los errores de autenticación, validación, tiempo de espera y del transportista.
• Detén las consultas rutinarias después de un estado terminal, de acuerdo con tus reglas operativas.
• Prueba las variaciones reales de las respuestas antes de mostrar mensajes de estado a los clientes.
• Vuelve a comprobar la documentación de FedEx al cambiar las versiones de la API o ampliar los tipos de envío.

Preguntas frecuentes

¿Puedo utilizar el sitio web de FedEx en lugar de la API?

Sí. El sitio web de FedEx suele ser la opción más sencilla para una consulta manual. Una API resulta útil cuando el software debe recuperar datos de seguimiento automáticamente, conectar eventos de estado con pedidos o mostrar información de seguimiento dentro de otra aplicación.

¿Necesito un token OAuth para cada solicitud de seguimiento?

Normalmente, la aplicación obtiene un token de acceso y lo envía con las solicitudes posteriores a la API hasta que expire. Almacena el token en caché de forma segura y sigue la documentación actual de autenticación de FedEx para conocer el comportamiento de expiración y actualización. No expongas el token al navegador ni al cliente.

¿Puede la API decirme exactamente dónde está un paquete?

Puede devolver los eventos de seguimiento y otra información proporcionada por FedEx para el envío. El resultado puede mostrar una ubicación de escaneo o una instalación, pero no debe interpretarse como un posicionamiento GPS continuo en tiempo real. Muestra únicamente la ubicación y el nivel de detalle del evento que se hayan devuelto.

¿Por qué a veces un número de seguimiento no tiene actualizaciones?

Es posible que se haya creado un envío sin un escaneo reciente, que el identificador sea incorrecto, que el evento aún no esté disponible en la respuesta o que el servicio del transportista no esté disponible temporalmente. Conserva el último resultado confirmado, muestra cuándo se comprobó e investiga los fallos repetidos en lugar de declarar que el envío se ha perdido.

¿Debería una empresa de comercio electrónico crear API independientes para cada transportista?

Puede ser razonable para una operación centrada en FedEx con sólidos recursos de ingeniería. Una empresa que realiza envíos mediante varios transportistas puede preferir una capa de seguimiento de múltiples transportistas para reducir el trabajo de integración y normalizar los eventos. Compara la cobertura de transportistas, el nivel de detalle de los datos, la fiabilidad, la documentación, el coste y el control sobre las experiencias orientadas al cliente antes de elegir.

Fuentes

• FedEx Developer Portal: Track API
• FedEx Developer Portal: Authorization API
• FedEx Developer Portal
• API de seguimiento de 17TRACK
• Documentación de la API de 17TRACK