Página de seguimiento de pedidos multitransportista — Guía completa (dftracking)

dftracking añade a su tienda PrestaShop una página de seguimiento de pedidos con su imagen de marca. El módulo consulta directamente las API de los transportistas (Colissimo, Mondial Relay, Chronopost, DHL), normaliza sus estados heterogéneos en un vocabulario común y los muestra en una timeline de cuatro etapas, junto al historial detallado de eventos de cada paquete.

Instalación

1. En el back office de PrestaShop, abra Módulos > Gestor de módulos.
2. Haga clic en Subir un módulo y suelte el archivo dftracking.zip.
3. Haga clic en Configurar una vez finalizada la instalación.

Durante la instalación, el módulo crea la tabla de caché ps_dftracking_shipment, genera un token de cron aleatorio y se registra en cuatro hooks: moduleRoutes (URL amigable /order-tracking), displayOrderDetail (botón «Seguir mi paquete» en el detalle del pedido), displayCustomerAccount (enlace en el área de cliente) y actionFrontControllerSetMedia (hoja de estilos de la página).

Credenciales API de los transportistas

Cada transportista tiene su propio sistema de autenticación. Rellene solo los que realmente utilice: un transportista sin configurar simplemente no se consulta, y el módulo recurre al enlace de seguimiento público.

Colissimo / La Poste

El conector utiliza la API Suivi v2 de la plataforma Okapi. Cree una cuenta gratuita en developer.laposte.fr, suscríbase a la API «Suivi» y pegue la clave Okapi en el campo Colissimo / La Poste — Clave API Okapi.

Mondial Relay

El conector utiliza el servicio WSI2_TracingColisDetaille. Introduzca su código Enseigne (normalmente 8 caracteres, por ejemplo BDTEST13 en el entorno de pruebas) y su clave privada, ambos facilitados en su contrato con Mondial Relay o desde Connect Hub. El módulo calcula automáticamente la firma MD5 que espera el servicio.

Chronopost

No se requieren credenciales: el conector se apoya en el endpoint público TrackingServiceWS, que acepta números de seguimiento sin autenticación. Los campos de cuenta y contraseña existen para configuraciones específicas, pero son opcionales.

DHL

El conector utiliza la API Shipment Tracking – Unified. Cree una cuenta en developer.dhl.com, suscríbase a esa API y pegue la clave en el campo DHL — Clave API. Atención a las cuotas del plan gratuito: la caché y el cron del módulo están diseñados precisamente para preservarlas.

Mapeo de transportistas

La sección Mapeo de transportistas lista todos los transportistas de su tienda y permite asignar un conector a cada uno. Dos mecanismos se combinan:

• Mapeo explícito — usted elige el conector en el desplegable. Es el método recomendado, sobre todo si sus transportistas usan nombres comerciales personalizados («Entrega exprés 24h», «Recogida en punto de entrega»…).
• Detección automática — para los transportistas dejados en «No rastreado», el módulo busca palabras clave en el nombre del transportista (colissimo, la poste, mondial relay, point relais, chronopost, dhl…) y aplica el conector correspondiente.

Personalización de la página de seguimiento

La sección Marca y visualización controla la apariencia de la página front:

• Color primario — títulos, etapa actual de la timeline, enlaces del transportista. Por defecto #2c3e50.
• Color de acento — etapas completadas y estado «Entregado». Por defecto #27ae60.
• Título personalizado — sustituye el título por defecto «Siga su pedido» en la parte superior de la página.
• Mostrar los productos del pedido — añade bajo la timeline la lista de artículos con miniaturas y cantidades.
• Duración de la caché (minutos) — véase la sección siguiente.

Los colores se inyectan como variables CSS en el contenedor de la página: el resto del diseño hereda de forma natural de su tema.

Caché y actualización

Cada paquete seguido ocupa una fila de la tabla ps_dftracking_shipment, que conserva el estado normalizado, los eventos en formato JSON, la URL de seguimiento del transportista y la marca de tiempo de la última actualización.

Dos mecanismos mantienen estos datos actualizados:

1. La tarea cron — mecanismo principal. Selecciona los paquetes no finalizados cuyos datos han superado la duración de caché, los actualiza por lotes y registra de paso los nuevos envíos de los pedidos de los últimos 60 días.
2. La actualización al visitar — red de seguridad. Si un cliente consulta su página de seguimiento con datos caducados, la API se consulta de inmediato.

En ambos casos, un paquete cuyo estado sea Entregado o Devuelto al remitente no vuelve a consultarse nunca: estos estados se consideran definitivos.

Configurar el cron

La URL del cron, token incluido, se muestra en la parte superior de la página de configuración del módulo. Prográmela cada 30 a 60 minutos:

*/30 * * * * curl -s "https://sutienda.com/index.php?fc=module&module=dftracking&controller=cron&token=SU_TOKEN" > /dev/null

El parámetro opcional &limit=100 limita el número de llamadas API por ejecución (50 por defecto, 200 como máximo). El endpoint responde en JSON: {"ok":true,"refreshed":12,"errors":0,"time":"…"}.

La página de seguimiento para el cliente

La página está disponible en /order-tracking (URL modificable en Parámetros de la tienda > Tráfico y SEO tras la instalación).

• Cliente conectado — el botón «Seguir mi paquete» aparece en el detalle de cada pedido, y se añade un enlace «Seguimiento de pedidos» al área de cliente. El módulo verifica siempre que el pedido pertenece al cliente conectado.
• Invitado — un formulario solicita la referencia del pedido y la dirección de email. Ambos deben coincidir para que el pedido se muestre; en caso de fallo, el mensaje de error es deliberadamente genérico y nunca revela si la referencia existe.

La timeline global refleja el paquete más avanzado del pedido. Debajo, cada envío dispone de su propia tarjeta: nombre del transportista, número de seguimiento, píldora de estado en color, historial detallado de eventos (fecha, descripción, lugar) y enlace al seguimiento oficial del transportista.

Estados normalizados

Las etiquetas propias de cada transportista se convierten en siete estados comunes, lo que permite una visualización homogénea sea cual sea el paquete:

• Pendiente de recogida — etiqueta creada, paquete aún sin escanear.
• En tránsito — el paquete circula por la red.
• En reparto — última etapa, ruta del día.
• Disponible en punto de recogida — paquete en espera en un punto o en una oficina.
• Entregado — estado final.
• Incidencia de entrega — anomalía comunicada por el transportista.
• Devuelto al remitente — estado final.

Pedidos multipaquete

El módulo lee la tabla order_carrier: cada número de seguimiento asociado al pedido se trata como un envío independiente, con su propio conector, estado e historial. Para tiendas antiguas donde el número de seguimiento solo se almacena en el pedido (shipping_number), un mecanismo de respaldo garantiza la compatibilidad.

Añadir un transportista

La arquitectura es deliberadamente abierta. Para integrar un transportista adicional:

1. Cree una clase en src/Adapter/ que extienda DftrackingAbstractCarrierAdapter.
2. Implemente getCode(), getLabel(), isConfigured(), getPublicUrl(), getNameKeywords() y fetch(). Este último devuelve un array status / events / tracking_url, reutilizando los ayudantes httpRequest(), event() y result() de la clase abstracta.
3. Añada la clase al array de DftrackingAdapterRegistry::all() y el require_once correspondiente en dftracking.php.

El nuevo conector aparece automáticamente en los desplegables de mapeo del back office.

Resolución de problemas

• La página muestra «Su pedido aún no ha sido enviado» — no hay número de seguimiento en el pedido. Añádalo desde la ficha del pedido en el back office, pestaña Transporte.
• El estado no se actualiza — compruebe primero que la tarea cron se ejecuta llamando a su URL manualmente en el navegador: la respuesta JSON indica el número de paquetes actualizados y de errores. Consulte después Parámetros avanzados > Registros: los fallos de llamada a la API se registran allí con el mensaje devuelto por el transportista.
• Error «tracking number not found» — normal en las horas siguientes a la creación de la etiqueta: el transportista aún no ha registrado el paquete. El módulo lo reintentará en el siguiente ciclo.
• Un transportista no se reconoce — la detección automática no ha encontrado ninguna palabra clave en su nombre. Asócielo explícitamente en la sección Mapeo de transportistas.
• El formulario de invitado no encuentra el pedido — la referencia y el email deben coincidir exactamente con los del pedido. Atención a los pedidos realizados con una dirección de email distinta a la de la cuenta de cliente.
• La página no usa mis colores — vacíe la caché de PrestaShop (Parámetros avanzados > Rendimiento) tras modificarlos, ya que la hoja de estilos queda cacheada por el tema.

Desinstalación

La desinstalación elimina la tabla ps_dftracking_shipment y todas las claves de configuración, incluidas sus credenciales API. Guarde una copia de estas si prevé reinstalar el módulo.