Cómo integrar la API de DHL Express en tu TMS

Si gestionas envíos DHL Express desde varios almacenes o centros de distribución, probablemente conoces esta escena: alguien del equipo de atención al cliente tiene una pestaña abierta en el portal de DHL todo el día, copiando estados de entrega a mano en el ERP porque el TMS no se entera de nada hasta que un cliente llama preguntando dónde está su pedido. Esta guía explica, endpoint por endpoint, cómo conectar la MyDHL API de DHL Express a tu TMS para automatizar cotización, creación de envíos y seguimiento, incluyendo el fallo más habitual que nadie te cuenta hasta que ya te ha pasado: la desactivación silenciosa del webhook.

Qué necesitas antes de empezar

Antes de tocar una línea de código, confirma que tienes estas cuatro piezas. Sin ellas, el desarrollo se detiene en el primer paso.

• Una cuenta de cliente activa con DHL Express. La propia documentación de DHL es explícita en esto: tu organización debe tener una cuenta de cliente activa con DHL Express antes de solicitar credenciales de API.
• Acceso al portal developer.dhl.com para registrar tu aplicación y generar API key/secret.
• Un TMS capaz de hacer llamadas REST salientes (JSON sobre HTTPS) y, esto es clave, un endpoint propio capaz de recibir peticiones POST entrantes. Sin esto último no podrás usar el servicio push, solo polling.
• Un perfil técnico que entienda BasicAuth, JSON y gestión de colas de mensajes. DHL lo deja claro en su propia ficha técnica: la API ha sido diseñada para uso de desarrolladores y necesitarás conocimiento básico de APIs REST, JSON y HTTPS.

Un detalle que sorprende a muchos equipos: las credenciales se conceden a nivel de aplicación, no de usuario. Cada integración (tu TMS, tu e-commerce, tu ERP) necesita su propio API key y secret, aunque los use la misma empresa.

Paso 1 — Solicitar credenciales y activar el entorno sandbox

Regístrate en developer.dhl.com, indica el caso de uso (rating, shipment, tracking) y DHL te proporciona acceso a un entorno de pruebas separado del de producción antes de darte acceso real. Este patrón no es exclusivo de DHL: es como funciona cualquier integración logística seria. Con la API de TRANSCEND, por ejemplo, el desarrollador trabaja primero en un entorno de desarrollo donde puede emitir documentos de prueba antes de pasar a producción, y una de las reglas básicas que recomiendan es clara: llama siempre a la versión documentada de la API y no asumas campos no declarados.

El entorno de test de DHL tiene un límite que debes conocer para no quedarte bloqueado a mitad de desarrollo: el entorno de test de DHL Express te proporciona un límite diario de 500 invocaciones de servicio para tus credenciales de acceso, y cuenta con SLAs formales para asegurar soporte con disponibilidad. Si tu equipo hace pruebas automatizadas en CI/CD, ese límite se agota rápido: reserva las invocaciones de sandbox para pruebas manuales de validación, no para tests unitarios que corren en cada commit.

Paso 2 — Autenticar las llamadas con BasicAuth

La autenticación de MyDHL API usa BasicAuth clásico sobre HTTPS, no OAuth2 con tokens de refresco. La documentación oficial lo especifica sin ambigüedad: el header de Authorization como parte de la petición debe configurarse de forma preventiva siguiendo el estándar BasicAuth. En la práctica, esto significa codificar en Base64 la combinación de tu API key y API secret y enviarla en cada llamada, no gestionar tokens con expiración.

Esto contrasta con la tendencia general del sector, donde cada vez más transitarios y proveedores logísticos migran hacia OAuth2 con API keys rotativas para el intercambio de datos. Si tu TMS ya tiene una capa de conectividad multitransportista pensada para gestionar credenciales de forma centralizada, este es el momento de usarla, en vez de hardcodear el header en cada microservicio que llama a DHL.

Paso 3 — Mapear los campos maestros entre tu TMS y el esquema de DHL

El mapeo de campos es donde la mayoría de integraciones fallan silenciosamente, no en la conexión inicial. Necesitas mapear como mínimo: número de cuenta DHL, tipo de servicio (Product Code), peso y volumen por bulto, Incoterm y código de contenido (ContentId).

DHL ha reforzado la validación numérica en versiones recientes de la API. Cualquier valor negativo o cero en campos de peso o valor provoca rechazo inmediato de la petición: se exige que los valores sean positivos para parámetros como totalNetWeight, totalGrossWeight, price, netValue weight, grossValue weight, el valor de additionalCharges, importCustomsDutyValue e importTaxesValue. Si tu TMS permite hoy que un operario registre "0" en el campo peso porque "ya se pesará en el CD", esa integración va a fallar en producción.

La misma lógica de mapeo robusto que aplica cualquier integración TMS-tercero de última milla es válida aquí. Como explica wheelhub sobre integraciones TMS en general, no basta con nombre y dirección: hace falta un ID Externo único que actúe como clave primaria vinculando el pedido en el TMS con el registro en el sistema de última milla, y geocoordenadas de latitud/longitud fundamentales para el geofencing. Aplícalo también aquí: guarda siempre el número de guía de DHL (AWB) como campo indexado en tu TMS, nunca como texto libre en observaciones.

Paso 4 — Probar en sandbox: cotización, creación de envío y etiqueta

Con credenciales de sandbox activas, el ciclo de prueba típico es: llamada de rating para obtener tarifa y tiempo de tránsito, llamada de creación de envío que devuelve número de guía y etiqueta (PDF o ZPL), y opcionalmente una llamada de tracking para confirmar que el envío existe en el sistema de DHL. Verifica en cada respuesta que recibes el número de guía, el archivo de etiqueta y, si aplica, el número de confirmación de recogida.

Failure mode #1: mercancías peligrosas bloqueadas sin aprobación previa. Este es el error que más tickets genera en producción y que nadie detecta en sandbox porque las cuentas de test no tienen restricciones reales. La regla es tajante: para enviar mercancías peligrosas con DHL Express MyDHL API, los clientes deben tener aprobación en sus números de cuenta DHL, concedida para ServiceCodes/ContentIds específicos mediante firma de contrato; si envían mercancías peligrosas sin esa aprobación o contrato, esos envíos quedan detenidos en la instalación de DHL. Solución práctica: añade un flag de validación en tu TMS que bloquee la creación del envío (no que lo envíe y falle después) cuando el código de producto detecte contenido peligroso y la cuenta no tenga el ServiceCode/ContentId aprobado.

Paso 5 — Configurar el seguimiento: pull vs push (webhooks)

Aquí es donde la mayoría de equipos cometen el error de quedarse en polling porque "funciona igual". No es cierto a escala. La diferencia entre consultar bajo demanda y recibir notificaciones proactivas es sustancial: la versión push de la Shipment Tracking Unified API envía actualizaciones de forma proactiva, permitiendo recibir notificaciones push sobre el estado de los envíos, incluyendo hora de entrega y actualizaciones de ruta.

El proceso de activación tiene un paso que se olvida con frecuencia: para la solución push, primero necesitas tu API key para crear una suscripción, y después necesitas el "subscription ID" y un "secret" para activarla. Tu endpoint receptor debe capturar ese secret y devolverlo en la confirmación, o la suscripción nunca queda activa.

Antes de que DHL cree el webhook, valida que tu endpoint responde correctamente: para ambos tipos de suscripción de webhook, antes de crearse se comprueba la validez de la URL mediante una petición HTTP GET, y el servidor debe responder con un código HTTP 200 para indicar que el endpoint es válido y está activo.

Failure mode #2, el crítico: reintentos y desactivación automática. Este es el fallo que puede dejarte semanas sin datos de tracking sin que nadie se dé cuenta, porque no genera ningún error visible en el TMS, simplemente deja de llegar información. El mecanismo de reintento de DHL funciona así: el sistema receptor debe usar un certificado SSL válido y responder al POST del evento con HTTP 200 en 5 segundos; si no se cumple, DHL reintenta la entrega en 1 hora, si la segunda entrega falla reintenta 6 horas después de ese segundo intento, y si la tercera falla el sistema no vuelve a intentar enviar ese evento concreto; si la entrega de eventos falla 10.000 veces consecutivas para un webhook específico, ese webhook se desactiva automáticamente y se notifica por email al contacto técnico de la cuenta.

La acción correctiva no es reactiva, es preventiva: monta un healthcheck que monitorice la disponibilidad de tu endpoint receptor de forma independiente al propio flujo de DHL, con alertas si el servicio cae más de unos minutos. 10.000 fallos consecutivos suenan a mucho margen, pero si tu endpoint cae un fin de semana largo con volumen alto de envíos, ese contador se consume más rápido de lo que crees.

Un matiz técnico adicional a vigilar tras cualquier actualización de DHL: los consumidores de la API pueden recibir ocasionalmente una respuesta 404 – No encontrado para envíos que antes estaban disponibles, un comportamiento esperado que refleja el ciclo de vida de datos actualizado del backend. No trates ese 404 como un error de integración; trátalo como retención de datos expirada y documenta el comportamiento para que el equipo de soporte no abra tickets innecesarios.

Paso 6 — Pasar a producción y confirmar que funciona

Antes de escalar a todo el volumen, define cómo sabrás que la integración funciona de verdad. La checklist mínima:

1. Comparar el evento recibido vía webhook contra el estado real mostrado en el portal MyDHL para el mismo número de guía.
2. Verificar que el TMS actualiza el ETA automáticamente al recibir el evento, sin intervención manual.
3. Configurar una alerta si no llega ningún evento de tracking tras un número determinado de horas desde la recogida, como red de seguridad ante una desactivación de webhook no detectada.
4. Repetir el ciclo completo (cotización, creación, etiqueta, tracking) con 2-3 envíos reales de bajo riesgo antes de abrir la integración a todo el volumen diario.

Cuándo una integración carrier-por-carrier deja de ser sostenible

Todo lo anterior es factible con un equipo técnico dedicado y DHL Express como único transportista relevante. El problema aparece cuando tu empresa trabaja simultáneamente con DHL Express, UPS, SEUR, Correos Express y dos o tres transportistas locales en México, Colombia o Chile. Cada uno tiene su propio esquema de autenticación, su propio formato de mapeo de campos y su propia lógica de webhooks. Mantener seis integraciones distintas, cada una con su ciclo de vida de credenciales y sus particularidades de reintento, multiplica el trabajo de IT sin multiplicar el valor para el negocio.

Aquí es donde entran las plataformas de conectividad multitransportista que ya mantienen estas integraciones por ti: soluciones como Cargoson, nShift, Sendcloud o ShipEngine ofrecen esa capa de "carrier connectivity" ya construida y probada contra los cambios de API de cada transportista, dejando al equipo de compras centrado en negociar tarifas y KPIs en lugar de mantener código de integración.

La industria se mueve claramente en esta dirección porque el modelo anterior ya no aguanta el volumen actual. Como resume la guía de conectividad con transitarios de OVRSEA sobre por qué el intercambio de archivos planos ha quedado atrás: un transitario moderno expone una API para que el dato de envío, estados, costes y documentos suba automáticamente al ERP o al TMS sin reintroducción manual. Lo mismo aplica a un transportista express como DHL: la arquitectura real para trazabilidad en 2026 se basa en webhooks y APIs RESTful, no en importaciones CSV nocturnas.

Próximos pasos

Resumiendo: solicita credenciales de aplicación en developer.dhl.com, valida BasicAuth en sandbox, mapea los campos numéricos con las validaciones estrictas de peso y valor, prueba el ciclo completo de rating-shipment-tracking, activa el webhook push con su secret de confirmación, y monitoriza activamente el endpoint receptor para no descubrir una desactivación por 10.000 fallos consecutivos tres semanas después de que ocurriera.

Una buena práctica que pocos equipos aplican de forma sistemática es revisar la integración cada seis meses, no solo cuando algo se rompe. DHL publica actualizaciones de esquema con cierta frecuencia (nuevos códigos de referencia, cambios de validación, migraciones de backend de tracking), y una revisión periódica te permite ajustar el mapeo antes de que un cambio no anunciado te llegue como incidencia en producción.