Introducción
El webhook es un método de arquitectura de software que se utiliza para automatizar notificaciones push entre las aplicaciones de origen y destino cuando se produce un nuevo evento.
El webhook se describe como un callback HTTPS definido por el usuario (normalmente, solicitud POST) desencadenado por un cambio en el estado de un evento concreto. Este envía notificaciones automatizadas casi en tiempo real (mensajes/información/datos) desde la aplicación de origen (lado del servidor) a la aplicación de destino (lado del cliente) siguiendo el concepto «reacción a evento» (es decir, no contacte conmigo; solo me pondré en contacto si tengo alguna novedad para usted).
Flujo de trabajo de la API frente al del webhook
La siguiente ilustración describe cómo se reciben los datos del evento en caso de solicitud de API y en el caso del webhook.
Resumen
El webhook de seguimiento de FedEx es un punto de conexión HTTP que recibe eventos de FedEx casi en tiempo real y ayuda a mejorar la experiencia global en la logística del recorrido de los envíos. Los clientes e-commerce de FedEx ahora pueden obtener visibilidad casi en tiempo real de los eventos del envío mediante notificaciones push seguras de seguimiento.
Ventajas y características del webhook de seguimiento
Los webhooks de seguimiento de FedEx proporcionan importantes ventajas competitivas, a saber:
- Una solución tecnológica modernizada con capacidad de autoservicio.
- Interfaz intuitiva con consola de gestión de webhooks para brindar a los clientes la capacidad de gestionar ellos mismos los webhooks de seguimiento.
- Los webhooks de seguimiento son suscripciones basadas en cuenta FedEx.
- Reciba notificaciones sobre eventos de seguimiento de envíos casi en tiempo real y añada valor a la experiencia posterior al carrito de su cliente.
- Obtenga datos precisos sobre eventos de seguimiento con fecha de entrega estimada y plazo de entrega estimado.
Roles de FedEx Developer Portal:
Dentro de FedEx Developer Portal puede llevar a cabo distintas funciones dependiendo del rol configurado.
Para obtener más información sobre el FedEx Developer Portal, consulte la guía de administración de la organización.
Normas y buenas prácticas comerciales
- No se puede usar un número de cuenta de envío en varios webhooks.
- Solo los usuarios de FedEx Developer Portal con rol de administrador pueden acceder a las características y la documentación del webhook de seguimiento, gestionarlas y usarlas.
- Debe seleccionarse al menos un número de cuenta de envío disponible para poder crear un webhook de seguimiento.
- El punto de conexión o la URL de destino que cree el cliente debe cumplir los siguientes requisitos:
- Tener un host HTTPS.
- Responder a solicitudes POST y analizar las cargas útiles de JSON.
- Tener un host HTTPS.
- Seguridad del webhook: solo se admiten conexiones HTTPS que usen un protocolo TLS (SSL) 1.2 o superior configurado con un certificado de una autoridad de certificación válida. Añada a la lista blanca las siguientes direcciones IP para recibir actualizaciones procedentes de servidores FedEx sin interrupciones:
Dev/Beta Prod 169.63.102.107
150.239.111.98
169.59.163.56
169.63.176.128
150.239.215.211
150.239.210.140
Sandbox Console
Status
Success
Test webhook tracking event details delivered successfully
Error
Test webhook tracking event details delivery failed
- Mecanismo de computación por error cuando los webhooks no funcionan. Los clientes tendrán que recurrir a fuentes EDI o a solicitudes de sondeo de Track API para obtener las actualizaciones sobre eventos ignoradas durante interrupciones y averías.
- Puede que los clientes reciban a veces las actualizaciones del evento de seguimiento desordenadas y deban consultar la marca de tiempo del evento de escaneo para conocer el orden correcto.
- Eliminar cuentas en FedEx Developer Portal:
- El usuario/cliente no puede eliminar las cuentas:
- Si están asociadas a algún webhook.
Nota: Aquí se incluyen los webhooks de seguimiento activos o en pausa. - Si la cuenta está disponible o asociada a un proyecto.
- Si es la única cuenta en un proyecto/webhook.
Note: El usuario/cliente debe eliminar primero la cuenta del proyecto/webhook y luego eliminarla de la organización.
- Si están asociadas a algún webhook.
- Para que el usuario/cliente pueda eliminar las cuentas:
- La cuenta debe pertenecer a la misma organización.
- El usuario/cliente debe ser administrador para eliminar cuentas de la organización.
- El usuario/cliente no puede eliminar las cuentas:
Restricciones habituales
- Todos los envíos del cliente asociados a los números de cuenta de las compañías operativas FedEx Express®, FedEx Ground®, FedEx Freight® y FedEx Ground® Economy (anteriormente, FedEx SmartPost®) están dentro del alcance independientemente del destino o el origen (envío de importación, de exportación, internacional, nacional, etc.).
- El webhook solo admite números de cuenta de FedEx Freight corporativos de 9 dígitos.
Nota: Las cuentas solo de LTL Freight de 9 dígitos no se admiten; si desea añadir una cuenta de LTL Freight, debe ponerse en contacto con el servicio de atención al cliente para transferir una cuenta LTL a una cuenta corporativa. - Las empresas operativas FedEx Office, FDC y FedEx Custom Critical® están fuera del alcance.
- Los clientes deben encargarse de gestionar el orden de los eventos sobre seguimiento de envíos que reciban.
- Las notificaciones automatizadas por e-mail se envían cuando no hay actividad (guardado/fallido/crear/actualizar/poner en pausa/reanudar/cancelar/eliminar) en los webhooks de seguimiento suscritos.
- Traducciones:
- Las traducciones de la carga útil de seguimiento están disponibles en 41 idiomas (combinaciones).
Haga clic aquí para ver la lista de idiomas compatibles. - La traducción de notificaciones por e-mail está disponible solo para los idiomas de la región de Estados Unidos (combinación: en-US, es-US).
- Las traducciones de la carga útil de seguimiento están disponibles en 41 idiomas (combinaciones).
Nota: Las indicaciones anteriores están sujetas a cambios cuando se publiquen actualizaciones futuras.
Probar URL del webhook
Puede usar la función Probar URL de webhook para comprobar el tipo de datos de seguimiento que se devuelven a la URL de destino (servidor receptor/de escucha). Esto ayuda a validar la URL y los datos devueltos antes de crear un webhook de seguimiento.
Navegación:
A continuación, se describe cómo llegar a la consola del entorno de prueba Probar URL del webhook:
- Mis proyectos (en el panel de navegación de la izquierda) -> pestaña Webhooks -> botón Probar URL del webhook -> en la consola del entorno de pruebas, hacer clic en Probar este webhook
- Catálogo de API (en el panel de navegación de la izquierda) -> buscar Webhook de seguimiento/hacer clic en WEBHOOK en FILTROS -> tarjeta Webhook de seguimiento:
- -> Resumen -> botón Documentación -> en la consola del entorno de pruebas, hacer clic en Probar este webhook.
- -> Docs -> en la consola del entorno de pruebas, hacer clic en Probar este webhook
Pasos:
A continuación, se describen los pasos para usar la funcionalidad Probar URL del webhook:
- Haga clic en el botón Probar URL del webhook.
- Introduzca los siguientes parámetros de prueba:
Nombre del campo Descripción URL de destino
Esta es la URL para recibir la carga o los datos del evento de seguimiento.
- Los clientes deben proporcionar una URL de destino operativa y válida.
- La URL de destino proporcionada debe estar en formato sintáctico estandarizado (URL https segura).
Token de seguridad
Se usa como clave secreta compartida para autenticar y validar la respuesta al webhook de seguimiento.
- El valor del token debe tener una longitud mínima de 25 caracteres y máxima de 100 caracteres.
- Debe haber al menos 1 mayúscula, 1 minúscula y 1 número.
- El token de seguridad se usará para crear una firma HMAC (código de autenticación de mensajes basados en hashes) para la validación de respuestas.
Idioma de la carga
Seleccione el idioma que desee para las traducciones de los datos de seguimiento en la lista desplegable. Estos son los 6 idiomas de ejemplo disponibles:
- Inglés (Estados Unidos)
- Francés (Canadá)
- Chino (China)
- Alemán (Alemania)
- Japonés (Japón)
- Español (México)
Tipo de seguimiento
Seleccione el tipo de respuesta en la que tienen que recibirse los datos de seguimiento.
- Respuesta de seguimiento detallada (el tipo de respuesta consta de datos de seguimiento protegidos con el historial completo de eventos).
- Respuesta de seguimiento de evento específico (el tipo de respuesta cuenta con datos de seguimiento protegidos únicamente con la información de los eventos más recientes).
Eventos de seguimiento
Seleccione una categoría superior para recibir notificaciones por e-mail relacionadas con eventos del envío en el recorrido del mismo. Estas son las categorías superiores:
- Enviar
- En tránsito
- Entrega
- Excepciones
- Prueba de entrega
- Entrega estimada
Evento de estado
Un evento de seguimiento en el recorrido del envío. Seleccione uno de los eventos de seguimiento que se van a recibir. Estos son los 10 eventos de estado disponibles:
- Información sobre envío remitida a FedEx (etiqueta creada)
- Recogido
- En tránsito
- Artículo retenido en la oficina de entrega
- En proceso de envío
- Entregado
- Prueba fotográfica de la entrega
- Prueba firmada de entrega
- Fecha de entrega estimada
- Plazo de entrega estimado
Nota: Los valores del campo «Evento de estado» se rellenarán en función de la «Categoría de evento de seguimiento» seleccionada. Consulte la siguiente tabla para obtener más información sobre la «Categoría de evento de seguimiento» y sus respectivos «Eventos de estado».
Categoría de evento de estado Evento de estado Enviar
- Información sobre envío remitida a FedEx (etiqueta creada)
- Recogido
En tránsito
- En tránsito
- Artículo retenido en la oficina de entrega
Entrega
- En proceso de envío
- Entregado
Prueba de entrega
- Prueba fotográfica de la entrega
- Prueba firmada de entrega
Entrega estimada
- Fecha de entrega estimada
- Plazo de entrega estimado
- Marque la casilla Acuerdo de licencia de FedEx Developer Portal para firmar/aceptar el acuerdo de licencia.
- Haga clic en el botón PUSH para ver los resultados de la prueba.
Respuesta:
Estos son los parámetros de respuesta en el entorno de prueba:
- Cuerpo: el cuerpo contiene los parámetros de respuesta en la pestaña Probar URL del webhook dentro de la consola del entorno de pruebas.
- Estado: esta sección de la pestaña Resultados de la prueba le indica el estado de la solicitud procesada.
Ejemplo de mensaje satisfactorio:
Correcto
Detalles del evento de seguimiento del webhook de prueba entregados correctamente.
Si la entrega del evento de prueba es fallida, el ESTADO mostrará Error en la pestaña Resultados de la prueba con el código de error y el mensaje de error respectivos.
Ejemplo de mensaje de error:
Código de error:<<código de error>>
Error al entregar los detalles del evento de seguimiento del webhook de prueba.
Normas de validación:
- La URL del webhook debe estar en formato sintáctico estandarizado.
- Los campos obligatorios para probar una URL de webhook no pueden estar vacíos.
- Para una validación satisfactoria:
- FedEx enviará una solicitud con el evento de muestra JSON.
- La URL de destino del webhook debe responder con el código de estado HTTP 200 (OK) a FedEx.
- Para una validación insatisfactoria/fallida:
- Si FedEx recibe una respuesta que no sea 200 (OK), la validación de la URL de destino del webhook se considerará fallida.
- FedEx mostrará el código de error y el mensaje de error en la pestaña Resultados de la prueba
Proceso de validación de webhooks
Para crear un proyecto de webhook de seguimiento, primero hay que validar la URL del webhook. Tendrá que completar este proceso de validación antes de terminar de crear el proyecto de webhook (o para editar o reanudar un proyecto de webhook posteriormente). Este proceso permite a FedEx saber a quién y a dónde se envían los datos y también le permite a usted conocer el origen de los datos que FedEx le envía.
Cree una URL de destino y un token de seguridad (debe hacerse fuera de FedEx Developer Portal).
- Cree una URL de destino para recibir los mensajes y códigos de autenticación, así como las notificaciones de carga del webhook de seguimiento.
- Genere un token de seguridad que puede usarse como clave secreta para autenticar y validar información transmitida entre usted (cliente) y FedEx.
- Requisitos del token de seguridad:
- Una longitud mínima de 25 caracteres y máxima de 100 caracteres.
- 1 mayúscula
- 1 minúscula
- 1 número
Ejemplo:Y1F6OiVUQW2JPSElmRE9U0IY5
- Requisitos del token de seguridad:
¿Qué es MAC/HMAC y cómo se usa en el proceso de validación?
FedEx usa HMAC para validar la URL al crear, editar o reanudar un proyecto de webhook de seguimiento.
Un código de autenticación de mensajes (MAC) proporciona una forma de comprobar la integridad de la información transmitida o almacenada en un medio no fiable, basándose en una clave secreta. Normalmente, los MAC se usan cuando dos partes comparten una clave secreta a fin de validar la información transmitida entre ellas.
Se denomina HMAC al mecanismo MAC basando en funciones hash criptográficas. El HMAC puede usarse con cualquier función hash criptográfica (por ej., SHA256 en combinación con una clave secreta compartida). El HMAC se especifica en RFC 2104. El webhook de seguimiento de FedEx usa el HMAC SHA256.
Ejemplo (de un fragmento de pseudocódigo para ilustrar un hash HMAC SHA256):
- Primero, inicialice el MAC usando el algoritmo HmacSHA256 y el token de seguridad como clave secreta.
- Luego finalice la operación MAC codificando hexadecimalmente la carga de la solicitud enviada por FedEx.
- Este hash final debe coincidir con el valor del encabezado x-fedex-signature en el PUSH enviado por FedEx.
Mac mac = Mac.getInstance("HmacSHA256");
mac.init(new SecretKeySpec(secureToken.getBytes(), "HmacSHA256"));
devolver nueva String(Hex.encode(mac.doFinal(payLoad.getBytes())));
Nota: La clave secreta usada es el token seguro que usted proporcionará al configurar el webhook o al probar la URL de este.
Cómo funciona el webhook de seguimiento
El webhook de seguimiento permite a FedEx enviar datos seguros sobre eventos de seguimiento casi en tiempo real a una URL de destino para envíos asociados a determinados números de cuenta FedEx. Puede crear un proyecto de webhook de seguimiento para acceder a esta funcionalidad.
Crear webhook de seguimiento
Puede crear un webhook de seguimiento para enviar datos seguros sobre eventos de seguimiento casi en tiempo real a la URL de destino en el caso de envíos asociados a uno o varios números de cuenta FedEx.
El proceso de creación de un webhook de seguimiento consta de cuatro pasos:
- Paso 1: configurar proyecto
- Paso 2: introducir información del proyecto
- Paso 3: seleccionar cuentas de envío
- Paso 4: confirmar detalles y aceptar condiciones
Navegación:
A continuación, se describe cómo llegar a la página Webhook de seguimiento:
- Mis proyectos (en el panel de navegación de la izquierda) -> pestaña Webhooks -> +CREAR UN PROYECTO DE WEBHOOK
- Catálogo de API (en el panel de navegación de la izquierda) -> buscar Webhook de seguimiento/hacer clic en WEBHOOK en FILTROS -> tarjeta Webhook de seguimiento:
- -> Resumen -> botón Documentación -> +CREAR UN PROYECTO DE WEBHOOK
- -> DOCS -> +CREAR UN PROYECTO DE WEBHOOK
Pasos:
A continuación, se describe cómo crear un webhook de seguimiento:
- Haga clic en el botón +CREAR UN PROYECTO DE WEBHOOK.
- En la ventana emergente, seleccione una de las siguientes opciones del menú desplegable para especificar el tipo de empresa para el que necesita acceso al webhook.
- Envía con FedEx y necesita integrar los webhooks de FedEx en su sistema.
- Vende o facilita una solución de software que utiliza datos de FedEx y no es un proveedor de soluciones compatibles de FedEx.
Nota: Actualmente la solución Webhook de seguimiento de FedEx no está disponible para esta opción. - Es un proveedor de soluciones compatibles de FedEx.
Nota: Actualmente, la solución Webhook de seguimiento de FedEx no está disponible para esta opción. Como miembro del programa FedEx Compatible, si quiere acceder a Track API u otras soluciones de integración de FedEx, póngase en contacto con su gestor de canales. Si no sabe quién es, contacte con el administrador de su empresa.
- En la página Configurar webhook:
- a. Compruebe el número de cuenta de facturación por defecto que se muestra para su organización. Si desea cambiar el número de cuenta de facturación, haga clic en AÑADIR NÚMERO DE CUENTA A SU ORGANIZACIÓN (si tiene un solo número de cuenta) o SELECCIONAR OTRA CUENTA DE FACTURACIÓN (esta opción se muestra si su organización tiene varias cuentas de facturación).
Nota: Para comprobar la información sobre precios de los proyectos de webhook, consulte la página Resumen del webhook de seguimiento. - Seleccione las funciones que necesita y haga clic en Siguiente.
Nota: Para obtener más información sobre las funciones, haga clic en el icono de ayuda (?) que está junto a la función.
Nombre del campo Descripción Prueba de entrega
Esta función se usa para confirmar que un pedido ha llegado correctamente al destino previsto. Incluye lo siguiente:
- La prueba fotográfica de la entrega, que permite a los clientes recibir una foto que muestre la ubicación exacta de su paquete una vez que se entrega en su puerta.
- La prueba firmada de entrega, que permite a los clientes recibir una imagen de la firma del destinatario, así como su nombre y la fecha, la hora y la ubicación de la entrega.
Entrega estimada
Esta función ayuda a los destinatarios a planificar sus agendas proporcionando una fecha o un intervalo horario para las entregas de envíos. Incluye lo siguiente:
- Fecha de entrega estimada
- Plazo de entrega estimado
Eventos de seguimiento
Seleccione una categoría de evento para recibir notificaciones por e-mail cuando se produzcan eventos de seguimiento. Estos son los eventos de seguimiento:
- Enviar
- En tránsito
- Entrega
- Excepciones
- Opciones de entrega a medida
Filtrado basado en eventos
Incluye envíos de importación, de exportación o de terceros en la respuesta del webhook.
- a. Compruebe el número de cuenta de facturación por defecto que se muestra para su organización. Si desea cambiar el número de cuenta de facturación, haga clic en AÑADIR NÚMERO DE CUENTA A SU ORGANIZACIÓN (si tiene un solo número de cuenta) o SELECCIONAR OTRA CUENTA DE FACTURACIÓN (esta opción se muestra si su organización tiene varias cuentas de facturación).
- En la página Introducir detalles, introduzca los siguientes campos:
Nombre del campo Descripción Nombre del proyecto de webhook
Este es un nombre de proyecto de webhook que no está vacío, que es exclusivo y que no debe repetirse en otro webhook.
- El nombre del proyecto de webhook se completa automáticamente con una sugerencia que puede editarse según se necesite.
URL de destino
Esta es la URL para recibir la carga o los datos del evento de seguimiento.
- Los clientes deben proporcionar una URL de destino operativa y válida.
- La URL de destino proporcionada debe estar en formato sintáctico estandarizado (URL https segura, sin incluir fedex.com ni subdominios).
- El cliente puede repetir la URL de destino en varios webhooks.
Para obtener más información sobre la URL de destino y la seguridad del webhook, consulte la sección Normas y buenas prácticas comerciales.
Token de seguridad
Se usa como clave secreta compartida para autenticar y validar la respuesta al webhook de seguimiento.
- El valor del token debe tener una longitud mínima de 25 caracteres y máxima de 100 caracteres.
- Debe haber al menos 1 mayúscula, 1 minúscula y 1 número.
- El cliente puede repetir el token de seguridad en varios webhooks.
- El token de seguridad se usará para crear una firma HMAC (código de autenticación de mensajes basados en hashes) para la validación de respuestas.
Idioma de la carga (país)
Seleccione el idioma que desee para las traducciones de los datos de seguimiento en la lista desplegable.
Tipo de seguimiento
Seleccione el tipo de respuesta en la que tienen que recibirse los datos de seguimiento.
- Seguimiento detallado: este tipo de seguimiento consta de datos de seguimiento seguros con el historial completo de eventos.
- Seguimiento de evento específico: este tipo de seguimiento cuenta con datos de seguimiento protegidos únicamente con la información de los eventos más recientes.
Dirección de e-mail
Proporcione una dirección de e-mail.
Idioma del e-mail (país)
Seleccione el idioma preferido para recibir notificaciones por e-mail.
Nota:- La traducción de notificaciones por e-mail está disponible solo para los idiomas de la región de Estados Unidos (combinación: en-US, es-US).
- En la página Elegir cuentas de envíos, seleccione las cuentas que desea asociar al proyecto de webhook.
Nota:- Solo se mostrarán en la lista las cuentas que no estén asociadas a otros webhooks.
- Tiene que asociar al menos una cuenta al proyecto para continuar con el siguiente paso.
- Se pueden asociar hasta 100 cuentas a un solo proyecto de webhook mediante la IU del webhook. Puede añadir más cuentas usando la API de webhooks. Para obtener acceso a la API de webhooks, póngase en contacto con el servicio FedEx de atención al cliente o con asistencia técnica.
- En la página Confirmar detalles, compruebe los detalles del proyecto de webhook, lea y acepte los términos y condiciones y seleccione Crear para crear el proyecto de webhook.
Al enviar una solicitud correcta, se creará un nuevo webhook de seguimiento con un ID del webhook generado por el sistema y cuyo estado será Activo.
Normas de validación:
- El nombre del webhook debe ser exclusivo.
- La URL de destino del webhook debe estar en formato sintáctico estandarizado.
- Los campos obligatorios para crear un webhook no pueden estar vacíos.
- Debe asociarse al menos un número de cuenta de envío de FedEx para crear un webhook.
- Para una validación satisfactoria:
- Al crear un webhook con éxito, el cliente recibirá un mensaje de confirmación.
Ejemplo de mensaje de confirmación: <<Nombre del webhook>> se ha creado correctamente. Los cambios podrían tardar hasta 10 minutos en aplicarse.
- Al crear un webhook con éxito, el cliente recibirá un mensaje de confirmación.
- Para una validación insatisfactoria/fallida:
- Si FedEx recibe una respuesta que no sea 200 (OK) o 202 (Accepted), la validación de la URL de destino del webhook se considerará fallida.
Gestionar webhooks de seguimiento
La consola de gestión está disponible en FedEx Developer Portal para gestionar los webhooks de seguimiento. La consola presenta las opciones para editar, eliminar, poner en pausa y reanudar los webhooks de seguimiento activos/en pausa según sea necesario.
Navegación:
A continuación, se describe cómo llegar a la página GESTIONAR WEBHOOKS (consola de gestión de webhooks):
- Mis proyectos (en el panel de navegación de la izquierda) -> pestaña Webhooks -> página GESTIONAR WEBHOOK
Limitaciones habituales:
- El cliente siempre debe proporcionar una URL de destino https segura en formato sintáctico estandarizado y recibir validación como receptor de suscripciones activas.
- FedEx enviará datos del evento de seguimiento a la URL de destino del cliente en formato JSON estandarizado en el idioma seleccionado (combinación).
- Los campos exclusivos no pueden repetirse en varios webhooks: Nombre del webhook, ID del webhook y Número de cuenta de envío de FedEx.
- Cualquier cambio (GUARDADO/CREADO/EDITADO/REENVIADO/EN PAUSA/REANUDADO) en un webhook de seguimiento podría tardar hasta 10 minutos en aplicarse.
- Los webhooks de seguimiento ACTIVOS seguirán estando activos de forma indefinida a menos que:
- El webhook esté EN PAUSA o CANCELADO.
- El cliente solicite al asesor técnico que pause los webhooks de seguimiento.
- La opción Ver detalles está disponible únicamente para webhooks ACTIVOS y EN PAUSA.
- Los webhooks de seguimiento FALLIDOS o EN PAUSA estarán disponibles en la consola de gestión de webhooks solo durante 30 días.
- Si no se realiza ninguna acción (EDITAR/REANUDAR/ELIMINAR) en los próximos 30 días, los webhooks de seguimiento en pausa se cancelarán automáticamente.
- Si no se realiza ninguna acción (EDITAR y REANUDAR/ELIMINAR) en los próximos 30 días, los webhooks de seguimiento fallidos se eliminarán automáticamente.
- Los webhooks guardados para más adelante se mostrarán con el estado EN CURSO en la consola de gestión de webhooks solo durante 90 días.
- Si no se realiza ninguna acción (seguir creando o eliminar) en los siguientes 90 días, los webhooks de seguimiento en curso se eliminarán automáticamente.
Editar webhook
Puede usar esta opción para añadir, actualizar o eliminar información/detalles en los campos de un webhook de seguimiento ya presente.
Pasos:
Siga estos pasos para editar un webhook de seguimiento:
- Seleccione Mis proyectos en el panel de navegación de la izquierda.
- Seleccione la pestaña Webhooks.
- Seleccione el webhook en particular que aparece en Mis webhooks.
- Seleccione la acción Editar en los tres puntos verticales (⋮) que aparecen junto al webhook de seguimiento en cuestión.
- En la página Configurar webhook:
- Compruebe el número de cuenta de facturación por defecto que se muestra para su organización. Si desea cambiar el número de cuenta de facturación, haga clic en AÑADIR NÚMERO DE CUENTA A SU ORGANIZACIÓN (si tiene un solo número de cuenta) o SELECCIONAR OTRA CUENTA DE FACTURACIÓN (esta opción se muestra si su organización tiene varias cuentas de facturación).
- Seleccione las funciones que necesita y haga clic en Siguiente.
Nota: Para obtener más información sobre las funciones, haga clic en el icono de ayuda (?) situado junto a la función.
- En la página Introducir detalles, seleccione los cambios que desea editar y haga clic en Siguiente.
- En la página Seleccionar cuentas de envío, añada o elimine las cuentas asociadas al webhook y pulse Siguiente.
- En la página Confirmar detalles, compruebe los cambios realizados en el proyecto de webhook y pulse Siguiente para confirmar.
Al enviar una solicitud correcta, se actualizará el webhook, el cual seguirá ACTIVO.
Normas de validación:
- Cuando los cambios se actualizan correctamente, debe recibir un mensaje de confirmación.
Ejemplo de mensaje de confirmación: <<Nombre del webhook>> se ha actualizado correctamente. Los cambios podrían tardar hasta 10 minutos en aplicarse.
- La validación insatisfactoria/fallida:
- La validación de la URL de destino se considera fallida si FedEx recibe otras respuestas que no sean 200 (OK) o 202 (Accepted).
Nota:
- El ID del webhook asociado a un webhook de seguimiento ya presente permanece inalterado cuando un cliente edita/actualiza los webhooks.
- Los cambios actualizados de un webhook de seguimiento existente tardarán 10 minutos en aplicarse.
- Si hace clic en Cancelar durante la edición del webhook de seguimiento, este flujo de trabajo se interrumpirá y se le redirigirá a la página anterior (página Consola de gestión de webhooks).
- Cuando una cuenta se asocia a un webhook de seguimiento, FedEx enviará eventos de nuevos envíos creados a partir de entonces para dicha cuenta.
- Al desvincular una cuenta de un webhook de seguimiento, FedEx enviará todos los datos de los envíos ya emparejados o en vuelo y no enviará datos de los nuevos envíos creados a partir de entonces.
Ver detalles del webhook
Puede usar esta opción para ver detalles/configuraciones de un webhook de seguimiento existente.
Pasos:
Siga estos pasos para ver un webhook:
- Seleccione Mis proyectos en el panel de navegación de la izquierda.
- Seleccione la pestaña Webhooks.
- Seleccione el webhook en particular que aparece en Mis webhooks.
- Seleccione la acción Ver detalles en los tres puntos verticales (⋮) que aparecen junto al webhook de seguimiento en cuestión.
La página Ver detalles contiene lo siguiente:
- Nombre del webhook
- Los tres botones de acción basados en el estado del webhook son:
- Editar webhook
- Poner en pausa/reanudar webhook
- Cancelar webhook
- La pestaña Detalles del proyecto de webhook consta de los siguientes campos y sus valores respectivos:
- Detalles de facturación
- Estado del proyecto
- Número de cuenta de facturación
- Información del proyecto
- Nombre de proyecto
- URL de destino
- ID del webhook
- Idioma de la carga
- Tipo de seguimiento
- Dirección de e-mail
- Idioma del e-mail
- Funciones seleccionadas
- Política de reintentos
- Prueba de entrega
- Entrega estimada
- Eventos de seguimiento
- Filtrado basado en eventos
- Números de cuenta de envío basados en webhook.
- Detalles de facturación
- Pestaña de detalles del Historial de proyectos de webhook:
esta pestaña muestra los detalles de las acciones realizadas para el webhook en cuestión, como la hora en que se puso en pausa, editó, etc.
Poner webhook en pausa
Puede usar esta opción para poner en pausa un webhook si no desea recibir datos de seguimiento temporalmente.
Pasos:
A continuación, se describen los pasos para poner en pausa un webhook:
- Seleccione Mis proyectos en el panel de navegación de la izquierda.
- Seleccione la pestaña Webhooks.
- Seleccione el webhook en particular que aparece en Mis webhooks.
- Seleccione la acción Poner en pausa en los tres puntos verticales (⋮) que aparecen junto al webhook en cuestión.
- Introduzca el motivo para poner en pausa el webhook en el cuadro de texto MOTIVO DE LA PAUSA.
- Haga clic en PONER EN PAUSA para enviar la solicitud.
Respuesta:
- Al poner en pausa un webhook correctamente, recibirá un mensaje de confirmación.
Ejemplo de mensaje de confirmación:
<<Nombre del webhook>> se ha puesto en pausa correctamente. FedEx dejará de enviar datos de eventos de envíos a partir de ahora. Los cambios podrían tardar hasta 10 minutos en aplicarse.
- Cuando un webhook no puede ponerse en pausa, recibirá el código de error y el mensaje de error respectivos.
Ejemplo de mensaje de error: No podemos procesar su solicitud por el momento. Inténtelo de nuevo más tarde.
Código de error: <<código de error>>
Limitaciones:
- Todos los webhooks en pausa estarán disponibles en la consola de gestión de webhooks solo durante 30 días.
- Si no se realiza ninguna acción (EDITAR/REANUDAR/CANCELAR) en los próximos 30 días, los webhooks en pausa se eliminarán automáticamente.
Nota:
- Cuando un webhook está en pausa, FedEx no enviará los datos de eventos de envíos ya emparejados o en vuelo ni los datos de eventos de nuevos envíos creados a partir de entonces.
Reanudar webhook
Puede usar esta opción si un webhook se tiene que reanudar o volver a activar.
Pasos:
A continuación se describen los pasos para reanudar un webhook:
- Seleccione Mis proyectos en el panel de navegación de la izquierda.
- Seleccione la pestaña Webhooks.
- Seleccione el webhook en particular que aparece en Mis webhooks.
- Seleccione la acción Reanudar en los tres puntos verticales (⋮) que aparecen junto al webhook pausado en cuestión.
- Introduzca el motivo para reanudar el webhook en el cuadro de texto MOTIVO DE LA REANUDACIÓN.
- Haga clic en REANUDAR para enviar la solicitud.
Nota:
- El plazo para reanudar un webhook pausado es de 30 días.
- Cuando un webhook se reanuda, FedEx envía datos de nuevos eventos de envíos ya emparejados o en vuelo y de nuevos envíos creados a partir de entonces.
Validación:
- El nombre del webhook debe ser exclusivo.
- La URL de los webhooks debe estar en formato sintáctico estandarizado.
- Los campos obligatorios del webhook no pueden estar vacíos.
- Debe permanecer seleccionado al menos un número de cuenta disponible para poder reanudar un webhook.
- Validación satisfactoria:
- Al reanudar el webhook con éxito, el cliente recibirá un mensaje de confirmación.
Ejemplo de mensaje de confirmación:
<<Nombre del webhook>> se ha reanudado correctamente. FedEx empezará a enviar datos de eventos de envíos a partir de ahora. Los cambios podrían tardar hasta 10 minutos en aplicarse.
- Al reanudar el webhook con éxito, el cliente recibirá un mensaje de confirmación.
- Validación insatisfactoria/fallida:
- Si FedEx recibe una respuesta que no sea 200 (OK) o 202 (Accepted), la validación de la URL de destino del webhook se considerará fallida.
- El cliente recibirá un código de error y un mensaje de error.
Ejemplo de mensaje de error: No podemos procesar su solicitud por el momento. Inténtelo de nuevo más tarde.
Código de error: <<código de error>>
Eliminar webhook
Si un webhook guardado o fallido ya no se necesita, use esta opción para eliminarlo.
Pasos:
A continuación, se describen los pasos para eliminar un webhook:
- Seleccione Mis proyectos en el panel de navegación de la izquierda.
- Seleccione la pestaña Webhooks .
- Seleccione el webhook en particular que aparece en Mis webhooks.
- Seleccione la acción Eliminar en los tres puntos verticales (⋮) que aparecen junto al webhook en cuestión.
- Puede eliminar el webhook en la pantalla Editar con el botón ELIMINAR.
Respuesta:
- Al eliminar un webhook correctamente, recibirá un mensaje de confirmación.
Ejemplo de mensaje de confirmación: <<Nombre del webhook>> se ha eliminado correctamente.
- Si la eliminación del webhook no se ha completado, recibirá un mensaje de error.
Ejemplo de mensaje de error: No podemos procesar su solicitud por el momento. Inténtelo de nuevo más tarde.
Código de error: <<código de error>>
Nota:
- Los webhooks eliminados no pueden recuperarse.
- Cuando un cliente elimina un webhook activo/en pausa, FedEx no enviará los datos de eventos de envíos ya emparejados o en vuelo ni los datos de eventos de nuevos envíos creados a partir de entonces.
Cancelar webhook
Si un webhook activo o en pausa ya no se necesita, use esta opción para cancelarlo.
Pasos:
A continuación, se describen los pasos para cancelar un webhook:
- Seleccione Mis proyectos en el panel de navegación de la izquierda.
- Seleccione la pestaña Webhooks .
- Seleccione el webhook en particular que aparece en Mis webhooks.
- Seleccione la acción CANCELAR en los tres puntos verticales (⋮) que aparecen junto al webhook en cuestión.
- Puede cancelar el webhook en la pantalla Editar con el botón CANCELAR.
Respuesta:
- Al cancelar un webhook correctamente, recibirá un mensaje de confirmación.
Ejemplo de mensaje de confirmación: <<Nombre del webhook>> se ha cancelado correctamente.
- Si la cancelación del webhook no se ha completado, recibirá un mensaje de error.
Ejemplo de mensaje de error: No podemos procesar su solicitud por el momento. Inténtelo de nuevo más tarde.
Código de error: <<código de error>>
Nota:
- Los webhooks cancelados no pueden recuperarse. Los webhooks cancelados seguirán visibles en la página de gestión de webhooks durante 90 días. Solo puede ver los detalles de los webhooks cancelados. Pasados 90 días, se eliminarán automáticamente.
- Cuando un cliente cancela un webhook activo/en pausa, FedEx no enviará los datos de eventos de envíos ya emparejados o en vuelo ni los datos de eventos de nuevos envíos creados a partir de entonces.
Buscar webhook
Puede buscar webhooks por su nombre, URL de destino, ID y número de cuenta.
Clasificar webhook
Puede clasificar los webhooks en orden ascendente o descendente por nombre, fecha de última modificación y estado para verlos mejor.
Filtrar webhook
- Puede filtrar webhooks por un único estado (activo/en pausa/en procesamiento/fallido) o seleccionando varios estados del webhook.
- Puede borrar la selección de filtros haciendo clic en el botón BORRAR TODO.
Procesar webhook
- Cuando una solicitud de creación o edición de webhook tarda más de 6 segundos, el estado pasará a ser «PROCESANDO».
- Los webhooks que se están procesando están inhabilitados. Con este estado no se puede realizar ninguna acción.
- Cuando el estado del webhook pasa a ser «PROCESANDO», se muestra el siguiente mensaje: «Su solicitud para [nombre del proyecto de webhook] está tramitándose; regrese cuando se haya completado».
Webhook fallido
- Cuando una solicitud de creación de webhook «PROCESANDO» resulta fallida, el estado pasará a ser «FALLIDO».
- Cuando un webhook presenta el estado «FALLIDO», solo puede realizar las siguientes dos acciones:
- Editar y reenviar
Con esta acción puede editar y enviar la suscripción fallida (puede enviar la solicitud tal cual o editar los detalles y volver a enviar la solicitud). - Eliminar
Con esta acción puede eliminar el webhook fallido.
- Editar y reenviar
Limitaciones
- Los webhooks de seguimiento FALLIDOS estarán disponibles en la consola de gestión de webhooks solo durante 30 días.
- Si no se realiza ninguna acción (EDITAR y REANUDAR/ELIMINAR) en los próximos 30 días, los webhooks de seguimiento fallidos se eliminarán automáticamente.
Características del webhook de seguimiento para el rol de administrador:
A continuación, se indican las características disponibles del webhook para un administrador:
- Probar URL del webhook
- Crear webhooks
- Guardar webhooks
- Ver detalles de webhooks
- Editar/actualizar webhooks
- Poner en pausa/reanudar webhooks
- Cancelar webhooks
- Eliminar webhooks
- Buscar/clasificar/filtrar webhooks
- Añada roles de colaborador y espectador al proyecto.
Detalles de las funciones del webhook
Política de reintentos
Esta función evita que FedEx envíe datos de eventos de seguimiento en caso de problemas en el lado del cliente. FedEx retendrá los datos y tratará de reenviarlos en un plazo de 6 horas.
Si FedEx no recibe una respuesta satisfactoria en dicho lapso de tiempo, FedEx detendrá el reenvío de ese evento.
Para obtener más información sobre las políticas de reintento, consulte la sección Mecanismo de reintento y nueva entrega.
Prueba de entrega
Esta función se usa para confirmar que un pedido ha llegado correctamente al destino previsto. Incluye lo siguiente:
- La prueba fotográfica de la entrega, que permite a los clientes recibir una foto que muestre la ubicación exacta de su paquete una vez que se entrega en su puerta.
Los webhooks proporcionan imágenes de la prueba fotográfica de la entrega en la carga JSON en formato Base64. Las imágenes pueden luego pasarse al formato JPEG.
Nota:- La prueba fotográfica de la entrega está disponible en EE. UU., Canadá, Puerto Rico, Hong Kong, Nueva Zelanda, Reino Unido e Irlanda.
- La prueba fotográfica de la entrega solo está disponible para FedEx Ground y FedEx Express y para envíos/direcciones residenciales.
- La prueba fotográfica de la entrega está disponible para entregas elegibles cuando no se requiere la prueba firmada de entrega. La prueba fotográfica de la entrega y la prueba firmada de entrega no están disponibles a la vez.
- La prueba fotográfica de la entrega está disponible para entregas en las que no se precisa firma y que no se realizan directamente a un cliente (por ej., realizadas directamente a un cliente durante la entrega).
- La prueba firmada de entrega, que permite a los clientes recibir una imagen de la firma del destinatario, así como su nombre y la fecha, la hora y la ubicación de la entrega. La información sobre la prueba firmada de entrega se presentará como una matriz de datos en lugar de como una imagen. La matriz de datos es una cadena codificada en Base64, que debe descodificarse para obtener la imagen final de la firma en formato PNG.
Para obtener más información sobre casos concretos de la prueba firmada de entrega y la prueba fotográfica de la entrega con los eventos de seguimiento correspondientes, consulte Casos de uso de la prueba firmada de entrega y la prueba fotográfica de la entrega.
Entrega estimada
Esta función ayuda a los destinatarios de los envíos a planificar sus agendas proporcionando una fecha o un intervalo horario para las entregas de envíos. Incluye lo siguiente:
- Fecha de entrega estimada: esta opción proporciona al destinatario una fecha de entrega estimada del envío. Por ejemplo: 20 de noviembre 20XX.
- Plazo de entrega estimado: esta opción proporciona al destinatario un plazo de entrega estimado para el envío en el día de la entrega real. Por ejemplo: entre las 14:00 y las 18:00.
Eventos de seguimiento
Esta función permite a los clientes conocer el estado de sus envíos a través de notificaciones por e-mail. Ofrece a los clientes opciones para elegir la fase exacta del proceso de envío o los eventos para los que desean recibir una notificación/alerta. Los eventos de envío disponibles son los siguientes:
- Envío: esta opción genera una notificación cuando se produce el evento de envío seleccionado. Por ejemplo: etiqueta creada, recogida, etc.
- En tránsito: esta opción genera una notificación para los eventos de tránsito del envío. Por ejemplo: en tránsito, artículo retenido en la oficina de entrega, etc.
- Entrega: esta opción genera una notificación para los eventos de entrega del envío. Por ejemplo: en proceso de entrega, entregado, etc.
- Excepciones: esta opción genera notificaciones para excepciones de entrega. Ejemplo: retrasos en el despacho de aduanas, etc.
- Opciones de entrega a medida: seleccione esta opción para recibir notificaciones de eventos de seguimiento personalizados. Por ejemplo: solicitud de retener en oficina aceptada, etc.
Filtrado basado en eventos
Esta función permite a los clientes organizar sus proyectos de webhook en función de los métodos de facturación de los envíos. Las opciones son las siguientes:
- Envío de importación: seleccione esta opción para los envíos que se le entregarán a usted y que usted, como destinatario, pagará.
- Envío de exportación: seleccione esta opción para los envíos que usted enviará y que usted, como remitente, pagará.
- Terceros: seleccione esta opción para envíos de importación y de exportación facturados a usted como tercero pagador.
Nota: Su número de cuenta FedEx se usará para la facturación o el pago de los envíos. En caso de que sea tercero pagador, puede que no sea el remitente o el destinatario, pero los gastos se cargarán en su número de cuenta FedEx.
Deshabilitar/reactivar la funcionalidad Webhook de seguimiento en Fedex Developer Portal
DESHABILITAR:
- Si desea deshabilitar la funcionalidad Webhook de seguimiento de forma temporal o permanente, puede ponerse en contacto con su asesor tecnológico de FedEx correspondiente para solicitarle que lo haga.
- Después de deshabilitar la funcionalidad Webhook de seguimiento, no tendrá acceso a ninguna funcionalidad ni documentación relacionada con los webhooks de seguimiento en FedEx Developer Portal.
REACTIVAR:
En un plazo de 30 días:
- Si desea reactivar la funcionalidad Webhook de seguimiento en un plazo de 30 días, tiene que ponerse en contacto con su asesor tecnológico correspondiente para solicitarle que lo haga.
- Después de reactivar la funcionalidad Webhook de seguimiento, volverá a tener acceso a todas las funcionalidades y la documentación relacionadas con los webhooks de seguimiento en FedEx Developer Portal.
- Por defecto, todos los webhooks asociados a su organización estarán «EN PAUSA». Tendrá que cambiar manualmente el estado de cada uno a «ACTIVO» para empezar a recibir actualizaciones de eventos de seguimiento.
- Si no se realiza ninguna acción en 30 días para los webhooks de seguimiento EN PAUSA, FALLIDOS o GUARDADOS, los webhooks en pausa se cancelarán automáticamente, y los webhooks fallidos o guardados se eliminarán automáticamente.
Después de 30 días:
- Si desea reactivar la funcionalidad Webhook de seguimiento pasados 30 días, tiene que ponerse en contacto con su asesor tecnológico correspondiente para solicitarle que lo haga.
- Después de reactivar la funcionalidad Webhook de seguimiento, volverá a tener acceso a todas las funcionalidades y la documentación relacionadas con los webhooks de seguimiento en FedEx Developer Portal.
- Por defecto, todos los webhooks asociados a su organización se eliminan de forma permanente. Será como activar la funcionalidad Webhook por primera vez, por lo que tendrá que empezar a crearlos de cero.
Nota: Recibirá una notificación por e-mail sobre la activación/deshabilitación de la funcionalidad Webhook de seguimiento para su organización.
Supervisión de fallos y mecanismo de reintento/nueva entrega
Tendrá que supervisar los fallos de forma interna y ponerse en contacto con su asesor técnico correspondiente si el fallo persiste.
Limitaciones del mecanismo de reintento:
- El mecanismo de reintento y nueva entrega (reintento de envío de datos de eventos) se pone en marcha solo cuando FedEx no recibe los códigos de estado HTTP 200 o 202 en la respuesta de la URL de destino. Estas acciones de reintento y nueva entrega tienen lugar durante un intervalo de 6 horas.
- Si FedEx intenta entregar datos de eventos y recibe otra respuesta diferente a la 200 o la 202, la transacción se considerará fallida.
- FedEx seguirá enviando datos de nuevos eventos cuando se produzcan a la vez que reintenta enviar los del evento original y los de cualquier evento posterior que suceda después de dicho webhook.
Lógica de reintento/nueva entrega:
Se realizarán un total de cuatro intentos de entrega para una notificación de evento del envío en un intervalo de seis horas desde que se produce el primer reintento del evento.
- Lógica de reintento:
- Intento 1:
Ejemplo: el número de seguimiento 823497234824 está «Entregado»; WMT envió la respuesta 400 (cualquier otro estado HTTP que no sea 200/202 se considera fallido). En este caso, el intento 1 se califica como fallido.- Intento 2 - 1 min +/jitter - Reintento 1
- Intento 3 - 2 min +/jitter - Reintento 2
- Intento 4 - 4 min +/jitter - Reintento 3
Nota: Los reintentos 2, 3 y 4 son válidos para cualquier intento de reentrega fallido.
Si FedEx recibe una respuesta positiva (estado HTTP 200/202) para alguna solicitud de reintento, detendrá el mecanismo de reintento para dicho evento.
- Intento 1:
- Intentos de reentrega:
- Intento de reentrega 1: se produce 30 minutos después del intento 1. Si falla, se harán 3 reintentos. Si los reintentos también fallan, el mecanismo pasa al intento de reentrega 2.
- Intento de reentrega 2: se produce 60 minutos después del intento 1. Si falla, se harán 3 reintentos. Si los reintentos también fallan, el mecanismo pasa al intento de reentrega 3.
- Intento de reentrega 3: se produce 3 horas después del intento 1. Si falla, se harán 3 reintentos. Si los reintentos también fallan, el mecanismo pasa al intento de reentrega 4.
- Intento de reentrega 4: se produce 6 horas después del intento 1. Si falla, se harán 3 reintentos. Si los reintentos también fallan, el evento se considerará fallido.
Nota:
- Después de 4 intentos de reentrega, si FedEx no recibe una respuesta positiva, detendrá el reenvío de ese evento.
- Si la conexión se restablece en un intervalo de 6 horas, FedEx intentará volver a entregar todos los eventos fallidos (entrega fallida con el mecanismo de reintento/nueva entrega).
Notas importantes:
- El mecanismo de reintento (reintento de envío de datos de eventos) se produce solo cuando FedEx no recibe los códigos de estado HTTP 200 o 202 en la respuesta de la URL de destino.
- Si FedEx intenta entregar datos de eventos y recibe otra respuesta diferente a la 200 o la 202, la transacción se considerará fallida.
- FedEx seguirá enviando datos de nuevos eventos cuando se produzcan a la vez que reintenta enviar los del evento original.
- FedEx también enviará datos de eventos que se produzcan después de dicho webhook.
Pausa automática (lógica de desactivación)
Si el número total de intentos insatisfactorios de nueva entrega supera el límite de reintentos definido, el webhook en cuestión se pondrá en pausa. FedEx le enviará un e-mail para informarle de que el webhook se ha puesto en pausa por la cantidad de intentos insatisfactorios y de que debe comprobar su URL de destino.
El máximo de intentos insatisfactorios permitido en una cola de reintentos es de 100 000. Si se supera este límite de intentos insatisfactorios, el webhook respectivo se pondrá en pausa y se enviará una notificación por e-mail a los suscriptores del webhook para informarles de que deben comprobar la conectividad de la red o el servidor.
Nota: Si un webhook está en pausa, el cliente no recibirá notificaciones de eventos para ningún envío hasta que reanude el webhook manualmente en el perfil de su organización.
El siguiente esquema describe la lógica de pausa automática:
Casos de uso para prueba firmada de entrega y prueba fotográfica de la entrega
Evento de seguimiento | Prueba firmada de entrega/prueba fotográfica de la entrega | Resultado | |
---|---|---|---|
Caso de uso 1 |
Entrega |
Seleccionadas |
Recibirá dos marcas de tiempo de la entrega:
Nota
|
Caso de uso 1.1 |
Entrega |
Sin seleccionar |
Solo recibirá la marca de tiempo del evento Entrega cuando se entregue el paquete.
|
Caso de uso 2 |
Envío/En tránsito/Excepciones |
Seleccionadas |
Solo recibirá una marca de tiempo de entrega para el evento Prueba firmada de entrega/prueba fotográfica de la entrega, que contendrá la marca de tiempo de la entrega y la matriz de datos de la imagen de la prueba firmada de entrega/prueba fotográfica de la entrega. Si no se selecciona Prueba firmada de entrega/prueba fotográfica de la entrega, no recibirá ninguna información de la marca de tiempo de la entrega. Nota
|
Caso de uso 2.1 |
Envío/En tránsito/Excepciones |
Sin seleccionar |
No recibirá ninguna información de la marca de tiempo de la entrega. Nota: No recibirá notificaciones de webhook para entregas de paquetes con y sin prueba firmada de entrega/prueba fotográfica de la entrega. |
Response