Los tracking webhooks de FedEx ofrecen actualizaciones de los envíos casi en tiempo real a lo largo de todo el ciclo de vida del envío.

A diferencia de las API de rastreo, que requieren que las aplicaciones soliciten el estado del envío, los webhooks envían automáticamente actualizaciones del envío a medida que hay nueva información disponible.

Esta guía abarca:

• Tres principios de integración
• Cómo funcionan los webhooks
• Cómo se procesan las cargas de webhook
• Notificaciones a los clientes
• Marcas de tiempo
• Mejores prácticas y problemas de integración habituales

Las integraciones de webhooks exitosas siguen tres principios.

Trata cada carga de webhook como una actualización del estado de un envío

No asumas que cada carga útil representa un nuevo estado de rastreo. FedEx publica una nueva carga cada vez que hay nueva información de envío disponible.

Una carga puede contener:

• Un nuevo evento de rastreo
• Predicciones de entrega actualizadas
• Información de la prueba de entrega
• Información del destinatario
• Otros cambios en los datos de envío

Varias cargas pueden compartir el mismo estado de rastreo, aunque contengan información de envío diferente.

Almacenar y combinar datos de envíos

Cada carga puede contener información nueva o actualizada sobre el envío. Almacena cada carga de webhook e incorpora la información nueva al registro de envío existente.

No sobrescribas el registro de envío existente con la carga más reciente. En cambio, conserva los datos de envío recibidos anteriormente e incorpora la información nueva para mantener un registro completo y actualizado de los envíos a lo largo de todo su ciclo de vida.

Utiliza reglas de negocio para impulsar acciones

Utiliza reglas de negocio para determinar cuándo actualizar los sistemas o notificar a los clientes.

No actives acciones únicamente a partir de un código de evento. Antes de actualizar las aplicaciones destinadas a los clientes o de enviar notificaciones, evalúa lo siguiente:

• Estado de rastreo
• Disponibilidad de los envíos
• Horario de notificación
• Requisitos de negocio

Modelo de procesamiento recomendado

El siguiente diagrama ilustra cómo los tres principios de integración de webhooks funcionan en conjunto en una implementación típica. Cada carga de un webhook se procesa como una actualización del estado del envío, se integra en un registro centralizado de envíos y se evalúa mediante reglas de negocio antes de que se actualicen las aplicaciones o se envíen notificaciones a los clientes.

Importante: Se pueden generar varias cargas de webhook para el mismo estado de rastreo. Procesa cada carga para asegurarte de que la nueva información del envío se incorpore al registro correspondiente.

Procesa cada carga de webhook como una actualización del estado de un envío.

No asumas que cada carga de webhook representa un nuevo estado de rastreo. FedEx envía una nueva carga cada vez que hay nueva información de envío disponible. Por ejemplo, un envío entregado puede generar cargas adicionales cuando se agregan o actualizan datos de prueba de entrega, información del destinatario u otros datos del envío.

Para cada carga, pregunta:

• ¿Qué estado de rastreo cambió?
• ¿Qué información del envío ha cambiado?
• ¿La actualización afecta a una aplicación destinada a los clientes?
• ¿La actualización activa una notificación?

Cómo procesar el historial de envíos

Supervisa tanto scanEvent como previousEvents.

• scanEvent contiene el estado de rastreo actual asociado a la carga útil.
• previousEvents contiene un historial adicional de envíos, incluyendo estados que tal vez no aparezcan como el scanEvent actual.

Algunos estados de rastreo aparecen en previousEvents en lugar de publicarse como un nuevo scanEvent. Las aplicaciones que solo procesan scanEvent pueden perder actualizaciones de envíos y generar historiales de envíos incompletos. Procesa ambas recolecciones para obtener una visión completa del envío.

Lleva un registro de tus envíos

Almacena cada carga de webhook e incorpora la información nueva al registro de envío existente.

Un registro completo de envíos ofrece visibilidad casi en tiempo real sobre:

• Paneles de control para el rastreo de envíos
• Aplicaciones de servicio al cliente
• Sistemas de gestión de pedidos (OMS)

Actualiza el registro del envío con cada carga para mantener una visión lo más precisa y completa posible del envío.

Elige una estrategia de notificaciones según las necesidades de tu negocio y el nivel de detalle que quieras proporcionar sobre los envíos.

Los tracking webhooks de FedEx envían actualizaciones sobre los estados del rastreo y los cambios en los datos de los envíos casi en tiempo real. Utiliza reglas de negocio para determinar qué actualizaciones son relevantes para tu negocio y cuáles pueden ignorarse.

Entre las estrategias de notificación más comunes se encuentran:

Notificaciones casi en tiempo real

Envía notificaciones inmediatamente después de que se produzca un estado de rastreo.

Ventajas

• Comunicación más rápida con los clientes
• Latencia mínima

Ten en cuenta: Es posible que aún no se cuente con información adicional sobre el envío.

Notificaciones enriquecidas

Espera unos minutos después de que se actualice el estado de rastreo para que pueda llegar información adicional sobre el envío.

Por ejemplo, después de entregar un estado, espera unos minutos para recopilar:

• Prueba de entrega (POD)
• Prueba de Entrega con Firma (SPOD)
• Prueba de entrega con GPS
• Información del destinatario

Ventajas

• Actualizaciones más completas sobre los envíos para los clientes
• Menos notificaciones de seguimiento
• Menos consultas de servicio de atención al cliente

FedEx recomienda esperar aproximadamente cinco minutos después de que se haya registrado un estado de entrega, ya que la información de la prueba de entrega suele agregarse poco después del momento inicial de la entrega.

Recomendaciones sobre el momento adecuado para notificar

El momento en que se envía la notificación varía según el cliente y el caso de uso. Sin embargo, las siguientes recomendaciones se utilizan habitualmente para las notificaciones a los destinatarios después de la compra. Para otros tipos de notificaciones (usuarios empresariales, representantes de servicio de atención al cliente, etc.), elige una estrategia de notificación que se adapte a tu caso de uso.

• Entrega estimada: Espera aproximadamente 15 minutos después de que estén disponibles tanto la fecha de confirmación como la primera fecha de entrega estimada (EDD).
• Listo para entrega: Envíalo de inmediato o según tu horario de trabajo (por ejemplo, todos los días a las 8:00 a. m.).
• Entregado: Espera aproximadamente 5 minutos para que se actualicen los detalles de la entrega.
• Intento de entrega: Aplica el mismo enfoque que en el caso de Entregado para permitir que llegue la información de entrega.

Creación de reglas de notificación basadas en datos de negocio

No todas las actualizaciones de un envío requieren una notificación. Define reglas de notificación que se adapten a tus necesidades de negocio.

Enfoque recomendado

No actives acciones únicamente a partir de un eventCode.

Evalúa:

• Estado de rastreo
• Datos necesarios para el envío
• Reglas de negocio

Genera notificaciones solo cuando haya información necesaria disponible.

Este enfoque ayuda a prevenir:

• Notificaciones duplicadas
• Falta información de entrega
• Notificaciones de entrega incompleta
• Notificaciones de seguimiento innecesarias

Usa la marca de tiempo adecuada según tu caso de uso.

• eventCreateTime: Momento en que ocurrió el evento de envío. Úsalo para el historial de rastreo de los clientes.
• Hora de envío del mensaje: Cuando FedEx envió la carga del webhook. Úsalo solo para depuración y monitoreo, no para experiencias dirigidas a los clientes.

eventCreateTime refleja el momento en que ocurrió el evento de envío. FedEx no actualiza este valor cuando se agrega información adicional sobre el envío posteriormente. Por ejemplo, un evento entregado se queda con el eventCreateTime original, incluso si las cargas posteriores agregan información de prueba de entrega u otras actualizaciones del envío. Como resultado, se debe utilizar eventCreateTime para identificar cuándo ocurrió el evento, y no cuándo se agregó la información relacionada con el envío.

En algunos casos, es posible que no se cuente con la hora de un evento. Cuando esto ocurre, la marca de tiempo puede contener un valor predeterminado de 00:00:00. Las cargas adicionales podrían incluir una marca de tiempo más precisa cuando esté disponible.

Mejores prácticas

• Procesa cada carga de los webhooks: cada mensaje puede contener un nuevo evento de rastreo o una actualización de los datos del envío.
• Incorpora las actualizaciones incrementales a tu registro de envío existente.
• Supervisa tanto scanEvent como previousEvents para obtener el historial completo del envío.
• Activa notificaciones a los clientes mediante reglas de negocio, no solo a partir de eventos sin procesar.
• Deja un margen de tiempo para los enriquecimientos previstos (por ejemplo, PPOD, SPOD, GPS) antes de notificar a los clientes.
• Diseña un procesamiento resiliente que gestione los mensajes duplicados y fuera de orden.

Problemas comunes de integración

• Asumir que cada carga útil representa un nuevo estado de rastreo.
• Sobreescribir el registro de envío con la carga más reciente.
• Basarse únicamente en scanEvent.
• Activar acciones únicamente a partir de un eventCode.
• Asumir que la primera carga entregada contiene todos los detalles de la entrega.
• Asumir que los mensajes de webhook llegan solo una vez o en orden cronológico.

Procesa cada carga de webhook como una actualización del estado de un envío. Almacena y combina las actualizaciones de los envíos, supervisa tanto scanEvent como previousEvents, y utiliza reglas de negocio para determinar cuándo actualizar las aplicaciones o notificar a los clientes.

Este enfoque ayuda a garantizar una visibilidad precisa de los envíos, un historial completo de rastreo y comunicaciones más informadas con los clientes.