Seguimiento DHL Automático y Multi-Transportista — Guía completa

El módulo DataFirefly Tracking consulta la API de DHL en tiempo real para seguir tus paquetes DHL eCommerce y DHL Express, hace avanzar automáticamente el estado de tus pedidos en la entrega y ofrece a tus clientes una página de seguimiento personalizada que cubre 19 transportistas. Esta guía cubre la instalación, la obtención de la clave API de DHL, la configuración, el cron, la página de seguimiento, la sincronización de estados, la adición de transportistas y la resolución de problemas.

Requisitos

• PrestaShop 8.0 a 9.x.
• PHP 8.1 a 8.3 con la extensión cURL activada.
• Para el seguimiento DHL: una clave de la API DHL «Shipment Tracking — Unified» (developer.dhl.com).
• Acceso a cron (tarea programada del servidor o servicio de cron) para el seguimiento automático.

Instalación

1. En el back-office, abre Módulos > Gestor de módulos, luego Subir un módulo y suelta el archivo datafirefly_tracking.zip.
2. Una vez instalado, abre la página de configuración con el botón Configurar.

En la instalación, el módulo crea sus tablas, registra sus hooks y genera automáticamente un token de cron.

Obtener la clave API de DHL

1. Crea una cuenta en developer.dhl.com.
2. Suscríbete a la API Shipment Tracking — Unified y crea una aplicación.
3. Copia la clave API (campo API Key).

Configuración

La página de configuración reúne los siguientes ajustes:

• DHL Tracking API Key: pega aquí tu clave API de DHL.
• Activar el polling: permite las actualizaciones automáticas de los paquetes DHL.
• Correos (Enviado, En tránsito, Entregado, Incidencia): preferencias de notificación por transición de estado.
• Actualizar el estado de PrestaShop en la entrega: activa la sincronización automática del estado del pedido.
• Retención del registro (días): cuánto tiempo se conservan las líneas de registro antes de la purga automática.

Guarda tus ajustes. Mientras la clave no esté indicada y el polling no esté activado, no se consulta ningún paquete DHL.

Transportistas compatibles

El módulo reconoce 19 transportistas, repartidos en dos categorías.

Seguimiento API en tiempo real (2)

DHL eCommerce y DHL Express: los estados se recuperan a través de la API de DHL, se normalizan (creado, en tránsito, entregado, incidencia) y se muestran en una cronología.

Enlace de seguimiento personalizado (17)

Colissimo, Chronopost, Shop2Shop, Mondial Relay, Relais Colis, Colis Privé, DPD, GLS, UPS, FedEx, TNT, La Poste, Poste Italiane, Correos, DHL Paket, bpost y PostNL: la página de seguimiento muestra un enlace a la página oficial del transportista, sin llamada a la API.

Creación automática del seguimiento

Cuando un pedido pasa al estado «Enviado», el módulo detecta el transportista, resuelve el número de seguimiento y crea la ficha de seguimiento. El número se busca, por orden, en:

1. la línea de transportista del pedido (order_carrier);
2. las etiquetas DHL Parcel (si procede);
3. el número AWB de DHL Express (si procede).

Para los paquetes DHL, el seguimiento se consulta luego automáticamente; para los demás transportistas, simplemente se asocia un enlace de seguimiento al pedido.

Configuración del cron

El cron activa el polling periódico de los paquetes DHL y recupera los envíos que el hook pudo no detectar (número indicado tras el paso a «Enviado», transportista sin módulo). Programa la siguiente URL cada 15 a 30 minutos:

curl "https://tu-tienda.com/module/datafirefly_tracking/cron?token=TU_TOKEN"

El token se genera en la instalación y se muestra en la configuración. Para una recuperación histórica puntual de pedidos antiguos, añade el parámetro days:

curl "https://tu-tienda.com/module/datafirefly_tracking/cron?token=TU_TOKEN&days=60"

La cuota API y el limitador

La API de DHL está limitada a 250 peticiones por día. El módulo incorpora un limitador que:

• cuenta las llamadas del día y detiene el polling de forma limpia al alcanzar el tope, y lo reanuda al día siguiente;
• espacia las consultas según el estado del paquete (más frecuentes ante una incidencia, más espaciadas para un paquete recién creado);
• deja definitivamente de consultar los paquetes entregados;
• abandona un número tras varios errores «no encontrado» (por ejemplo, un número no DHL introducido en un transportista DHL).

El contador del día es visible en la configuración y en la ficha de pedido.

Página de seguimiento del cliente

Un enlace «Seguir mi paquete» aparece en el detalle del pedido y en la cuenta del cliente. La página de seguimiento personalizada muestra una cronología de 4 etapas (Enviado, En tránsito, En reparto, Entregado) y el detalle de los eventos.

Es accesible:

• a los clientes con sesión iniciada, para sus propios pedidos;
• a los invitados, mediante el número de seguimiento junto con la referencia del pedido.

Seguimiento en el back-office

En cada ficha de pedido, una pestaña de seguimiento muestra la cronología, el último evento, el estado normalizado y un botón Actualizar para consultar DHL manualmente (dentro de la cuota). También se ofrece el enlace a la página de seguimiento oficial del transportista y a la página de seguimiento del front.

Sincronización de los estados del pedido

Cuando la opción Actualizar el estado de PrestaShop en la entrega está activada, el módulo hace avanzar el estado del pedido para los paquetes DHL:

• paquete entregado → estado «Entregado»;
• incidencia de entrega → estado «Error».

El cambio de estado activa los correos nativos de PrestaShop. El módulo impide cualquier retroceso: un pedido ya entregado no puede volver a «en tránsito».

Añadir un transportista

Todos los transportistas se describen en un registro central (la clase CarrierRegistry). Añadir un transportista consiste en añadir una sola entrada que contiene:

• su identificador interno y su etiqueta;
• los nombres de módulo (external_module_name) y los patrones de nombre para la detección;
• su URL de seguimiento (con los marcadores {tracking} y, si procede, {postcode});
• el indicador de seguimiento API o enlace, y la regla de validación del número.

Ninguna otra parte del módulo necesita modificarse: la detección, la URL, la etiqueta y el panel se derivan automáticamente.

Actualizar desde una versión anterior

La actualización se realiza reemplazando los archivos del módulo; PrestaShop aplica los scripts de migración automáticamente. La versión 1.1.0 amplía la columna de tipo de transportista para admitir los nuevos transportistas: este script es idempotente y conserva los datos existentes.

Resolución de problemas

• No se sigue ningún paquete DHL: comprueba que la clave API está indicada, que el polling está activado y que el cron se ejecuta.
• Error «clave API no válida»: asegúrate de usar la clave de la API Shipment Tracking — Unified, no la clave de envío DHL eCommerce.
• Cuota alcanzada: con 250 peticiones/día, el polling se detiene y se reanuda al día siguiente. Espacia el cron o reduce el número de paquetes activos si es necesario.
• Un paquete sigue sin encontrarse: tras varios errores «no encontrado», el módulo abandona el número (a menudo un número no DHL introducido en un transportista DHL).
• El estado del pedido no cambia: comprueba que la opción de actualización del estado está activada y que el paquete está realmente seguido por la API de DHL.
• Enlace de seguimiento PostNL incompleto: el código postal procede de la dirección de entrega; comprueba que está indicada en el pedido.

Desinstalación

La desinstalación elimina las tablas de seguimiento, registro y cuota del módulo, así como su configuración. Para una simple actualización, basta con reemplazar los archivos: el esquema y las fichas de seguimiento se conservan.