DHL Express - Crear Envío / Etiqueta

Descripción

Este modulo crea un envío en DHL Express a traves de su API REST. Recibe los datos del remitente y destinatario en formato JSON, junto con el código de producto DHL, peso del paquete y descripción del contenido. El modulo construye el payload completo incluyendo la fecha de envío planificada, configuración de cuenta, detalles de aduana (determinados automáticamente según si el envío es internacional) y opciones de etiqueta. Realiza una petición POST al endpoint /shipments de DHL Express y retorna el número de seguimiento, URL de rastreo, etiqueta en base64 y número de confirmación de despacho.

Configuración

Parámetro	Tipo	Requerido	Descripción
credentials_id	credentials	Si	Credencial DHL Express (provider: dhl_express)
shipper	textarea	Si	Datos del remitente en formato JSON con postalAddress y contactInformation
receiver	textarea	Si	Datos del destinatario en formato JSON
product_code	select	Si	Código de producto DHL: P (Express Worldwide), D (Express Worldwide Doc), U (Express Worldwide EU), K (Express 9:00), T (Express 12:00), Y (Express 12:00 Doc), N (Domestic Express)
weight	text	Si	Peso del paquete en kilogramos
description	text	Si	Descripción del contenido del envío
label_type	select	No	Formato de la etiqueta: PDF (por defecto), ZPL, LP2

Credenciales

Se requiere una credencial de tipo dhl_express con los siguientes campos:

api_key: API Key de DHL Express
account_number: Número de cuenta de DHL Express

Las credenciales se obtienen desde el portal de desarrolladores de DHL (https://developer.dhl.com/).

Salida

{
  "success": true,
  "shipment_id": "1234567890",
  "tracking_number": "1234567890",
  "tracking_url": "https://www.dhl.com/track/1234567890",
  "label_base64": "JVBERi0xLjQK...",
  "dispatch_confirmation": "DPC-001",
  "message": "Envio DHL creado - Tracking: 1234567890"
}

Ejemplo de Uso

Caso básico

{
  "credentials_id": "mi_credencial_dhl",
  "shipper": "{\"postalAddress\":{\"postalCode\":\"28001\",\"cityName\":\"Madrid\",\"countryCode\":\"ES\",\"addressLine1\":\"Calle Gran Via 1\"},\"contactInformation\":{\"fullName\":\"Mi Empresa\",\"phone\":\"+34600000000\",\"email\":\"envios@miempresa.com\"}}",
  "receiver": "{\"postalAddress\":{\"postalCode\":\"08001\",\"cityName\":\"Barcelona\",\"countryCode\":\"ES\",\"addressLine1\":\"Av Diagonal 100\"},\"contactInformation\":{\"fullName\":\"Cliente\",\"phone\":\"+34600000001\",\"email\":\"cliente@email.com\"}}",
  "product_code": "P",
  "weight": "2.5",
  "description": "Articulos electronicos",
  "label_type": "PDF"
}

API Utilizada

Endpoint: POST /shipments
Base: DHL Express API (via helper _dhlHelper)
Documentación: https://developer.dhl.com/api-reference/dhl-express-mydhl-api

Notas

La fecha de envío se establece automáticamente al momento de la creación
La declaración de aduanas se activa automáticamente cuando el pais de origen y destino son diferentes
Las dimensiones del paquete se establecen en 1x1x1 por defecto; para dimensiones especificas, modifique el JSON del shipper
El formato de etiqueta por defecto es PDF con plantilla ECOM26_84_001 a 300 DPI
El pickup se configura como no solicitado por defecto