DHL Parcel Poland Integration

El módulo DHL conecta WooCommerce con la API REST de DHL Parcel Poland para el seguimiento de envíos. Tú introduces el número de seguimiento en el pedido y el módulo obtiene de DHL el estado actual y el historial de eventos.

Configuración

Los ajustes de DHL pertenecen al grupo de envío de los ajustes PRO (opción polski_pro_shipping). Se leen y se guardan a través de la ruta REST de ajustes PRO, /wp-json/polski-pro/v1/settings, que exige la capacidad manage_woocommerce. Una pantalla propia de ajustes de envío está prevista, pero todavía no se ha publicado.

Autenticación de la API

Ajuste	Clave	Descripción
DHL activado	`dhl_enabled`	Activa el proveedor DHL
Clave de API de DHL	`dhl_api_key`	Bearer token del portal DHL WebAPI
Número de cuenta de DHL	`dhl_account_number`	Número de cuenta de cliente de DHL Parcel Poland

Puedes obtener la clave de API registrándote en developer.dhl.com y creando una aplicación con acceso a la DHL Parcel Poland API.

Activar el módulo

Envía dhl_enabled como true dentro del grupo shipping en un PUT a /wp-json/polski-pro/v1/settings
Envía dhl_api_key y dhl_account_number en la misma petición, porque el contenido guardado sustituye toda la opción
La sección de seguimiento del pedido pertenece al módulo Fulfillment, así que ese módulo debe estar activado en Polski > Módulos

Solo se consulta a DHL cuando dhl_enabled está activo y ambos campos están completos. Si falta alguno de esos tres elementos, el pedido sigue guardando el número de seguimiento y el enlace, pero no se obtiene el estado en vivo.

Registrar un número de seguimiento

Las etiquetas se crean en tus propias herramientas de DHL. Cuando tengas el número, guárdalo en el pedido:

Abre un pedido en WooCommerce > Pedidos
En la sección Shipment Tracking, selecciona el transportista DHL
Pega el número en Número de seguimiento
Deja URL de seguimiento vacía para que se genere el enlace, o pega el tuyo
Actualiza el pedido

El enlace de seguimiento de DHL se genera con el siguiente formato:

https://www.dhl.com/pl-pl/home/sledzenie-przesylek.html?tracking-id={number}

Actualizar el seguimiento en vivo

Cuando un pedido tiene número de seguimiento, la sección Shipment Tracking muestra una Vista previa en vivo con el botón Actualizar seguimiento en vivo. Ese botón llama a la API de seguimiento de DHL con tu Bearer token y muestra el estado actual y la lista de eventos (descripción, fecha, ubicación).

Cada consulta se guarda en caché durante 10 minutos. El botón vacía la caché de ese envío y vuelve a pedir los datos, así que úsalo cuando esperes un escaneo reciente.

Dónde aparece el seguimiento

Columna Tracking en la lista de pedidos: transportista, número, estado en vivo y enlace de seguimiento
Detalles del pedido en la cuenta del cliente, más la acción Seguir envío junto al pedido
Correos de pedido de WooCommerce, con el bloque de seguimiento añadido bajo la tabla del pedido
Avisos de estado Empaquetado, Enviado y Entregado, con transportista, número de seguimiento y enlace

Los tres estados también están disponibles como acciones masivas en la lista de pedidos: cambiar estado a Empaquetado, Enviado y Entregado.

Etiquetas y búsqueda de ServicePoint

La generación de etiquetas y la búsqueda de ServicePoint están escritas, pero no conectadas. DHLProvider contiene una llamada de etiqueta y una búsqueda de puntos de recogida, pero nada en el escritorio ni en la finalización de compra las alcanza, así que en pantalla no hay botón para generar etiquetas, ni etiqueta en PDF, ni buscador de puntos de recogida, y por ahora los envíos se crean en las propias herramientas de DHL.

Resolución de problemas

Síntoma	Causa	Solución
La vista previa en vivo no muestra estado	Módulo desactivado, o clave de API / número de cuenta vacíos	Guarda `dhl_enabled`, la clave de API y el número de cuenta mediante la ruta de ajustes
Actualizar no devuelve nada	Bearer token no válido (HTTP 401) o número de envío desconocido	Comprueba el token en los ajustes y el número en el pedido
El estado parece antiguo	La caché de consultas de 10 minutos	Pulsa Actualizar seguimiento en vivo
Respuestas vacías repetidas	Límite de solicitudes de DHL (HTTP 429)	Espera un momento y vuelve a actualizar

Filtros y acciones

El módulo DHL todavía no ofrece filtros públicos. Los datos de seguimiento se guardan en los metadatos del pedido, así que puedes establecerlos desde tu propio código:

// Guardar un número de seguimiento de DHL en un pedido.
$order = wc_get_order($orderId);
$order->update_meta_data('_polski_shipping_carrier', 'dhl');
$order->update_meta_data('_polski_tracking_number', '6230000123456789');
$order->save();

Si no defines _polski_tracking_url, el enlace de DHL se deriva del número al mostrar el seguimiento.