Cómo integrar la API de DSV con tu TMS

Si gestionas más de 5.000 envíos al año con DSV entre carga terrestre y paquetería exprés, cada reserva manual en myDSV es tiempo que tu equipo de logística no recupera. Integrar la API de DSV con tu TMS elimina esa doble introducción de datos, pero DSV no ofrece una única API: separa el catálogo por producto, cada uno con su propio modelo de autenticación. Esta guía te lleva paso a paso desde la suscripción en el DSV Developer Portal hasta el primer evento de tracking sincronizado en tu sistema, incluyendo el fallo de autorización que más tiempo hace perder a los equipos técnicos.

Qué vas a conseguir y qué necesitas antes de empezar

Al terminar esta integración, tu TMS o ERP generará reservas DSV automáticamente desde el pedido, descargará las etiquetas y recibirá los estados de seguimiento sin que nadie tenga que entrar en el portal de DSV a copiar datos. Antes de tocar una línea de código, necesitas tres cosas resueltas.

• Una cuenta de cliente DSV activa y aprobada: para carga terrestre necesitas cuenta DSV Road, y para integraciones de almacenaje o visibilidad de inventario, cuenta en DSV Contract Logistics.
• Una cuenta registrada en el DSV Developer Portal (developer.dsv.com), que es distinta de tu cuenta myDSV operativa.
• Saber qué API corresponde al tipo de envío: Road (SOAP) para carga terrestre nacional o europea, XPress (REST) para paquetería y envíos exprés, y Quote API para Air & Sea.

Esta distinción importa porque la DSV XPress Booking API crea envíos de tipo exprés/paquetería y recupera etiquetas de paquete, mientras que las operaciones de carga completa o LTL por carretera pasan por un esquema distinto dentro del mismo portal.

Paso 1: suscribirse a la API correcta en el DSV Developer Portal

El primer error habitual es suscribirse al producto equivocado porque DSV organiza su catálogo por modo de transporte, no por función. Dentro del portal verás categorías separadas: API - ROAD, API - AIR, SEA, RAIL, API - XPRESS, API - CONTRACT LOGISTICS y API - SCM. Cada una tiene su propia guía de desarrollador, su propio esquema OpenAPI y su propio proceso de aprobación.

Si lo que necesitas es seguimiento de envíos en lugar de reservas, el tracking requiere una suscripción aparte, no viene incluido automáticamente con la de booking. Como señala la documentación de AfterShip para este mismo escenario: "Subscribe to the DSV Tracking API in the DSV Developer Portal and use that key in AfterShip Tracking". Lo mismo aplica si conectas directamente sin pasar por una capa intermedia: la suscripción de tracking se gestiona de forma independiente de la de booking dentro del mismo portal.

Paso 2: obtener las dos credenciales (subscription key y access key)

Aquí es donde la mayoría de equipos técnicos se atascan la primera vez. DSV no usa un único token de API como Shopify o Stripe. DSV issues two keys: a subscription key from the Developer Portal and an access key from myDSV. Son dos sistemas distintos, con dos procesos de solicitud distintos, y los necesitas ambos antes de poder enviar una reserva real.

La aprobación no es instantánea. El equipo comercial de DSV revisa cada solicitud antes de activar el acceso, así que pide la credencial con margen respecto a la fecha de corte del proyecto. Para las APIs de Air, Sea y Rail el modelo cambia ligeramente: "For security reasons, you will need to have an active account at DSV Contract Logistics. Use your DSV Contract Logistics credentials (username & password) together with the DSV-Subscription-Key, available in the DSV Developer Portal profile" para solicitar un token de acceso OAuth 2.0.

Un detalle que suele pasar desapercibido: dos claves se asignan por cada producto suscrito, una "primary key" y una "secondary key", y solo una de ellas debe usarse en la cabecera HTTP "DSV-Subscription-Key". La segunda clave existe para rotación sin downtime, no para usar las dos a la vez.

Paso 3: superar la certificación antes de pasar a producción (obligatoria en XPress)

Si vas a integrar la Booking API de XPress, no puedes saltarte este paso: completar el proceso de certificación es un paso obligatorio del flujo de suscripción, justo antes de poder solicitar el paso a producción. El acceso al entorno de pruebas de certificación llega por correo una vez DSV aprueba tu solicitud de suscripción en el portal.

El flujo de reserva estándar para un envío doméstico o dentro de Europa se resuelve con dos llamadas:

1. Submit draft booking: envía los datos de la reserva a DSV. esto moverá un paquete de A a B, pero las reservas enviadas por este método no son procesadas por DSV todavía.
2. Confirm draft booking and download package label(s): confirma la reserva en borrador y descarga la etiqueta. este método confirma la reserva en borrador y envía la instrucción de reserva al transportista final.

Si el envío sale fuera de Europa o hacia un país restringido, hay un paso intermedio obligatorio: subir documentos relacionados con el transporte contra la reserva en borrador, como lista de empaque, certificados de mercancías peligrosas o factura comercial, ya que algunos documentos son obligatorios al enviar fuera de Europa o hacia un país restringido. Desde tu TMS, mapea como mínimo: direcciones de origen y destino, dimensiones, peso, tipo de servicio y, si hay despacho aduanero, códigos HS del producto.

Paso 4: conectar el seguimiento (Tracking, Shipment y Event API)

DSV ofrece varias formas de consultar el estado de un envío, y elegir la correcta depende de qué identificador tienes disponible en tu sistema. Para XPress, la API de tracking permite buscar por cuatro vías distintas: por DSV XPress Shipment ID, recuperando datos detallados del envío buscando por el ID recibido de la reserva vía API o a través del portal online de DSV XPress, por eventos asociados a ese mismo ID, por número de AWB, recuperando los eventos reales de un envío buscando por el número de AWB, o por el ID de seguimiento propio del transportista final.

Más allá de XPress, el ecosistema DSV más amplio divide la visibilidad en módulos independientes. Según la documentación técnica de Logistics Technology: el Product API da información sobre productos y servicios de DSV, el Schedule API permite obtener planes de fechas de entrega en tu zona, el Tracking API permite rastrear envíos y paquetes, el Shipment API da información de envío, y el Event API permite rastrear envíos y paquetes además de registrar y gestionar webhooks.

Aquí está el consejo que la mayoría de equipos aprende tarde: no hagas polling constante contra el Tracking API. Usa el Event API con webhooks. Cuando te suscribes a eventos de DSV, DSV envía notificaciones HTTPS POST a tu pushUrl configurada cada vez que ocurren eventos relevantes, como tracking, factura, visibilidad, cotización, almacenaje, declaración de aduanas o caída de la API. Esto reduce la carga sobre tu infraestructura y te da estados casi en tiempo real sin consumir tu cuota de llamadas.

Paso 5: probar el circuito completo antes de pedir el paso a producción

Antes de solicitar a DSV el "go-live", valida estos tres puntos en el entorno sandbox: la reserva de prueba genera un Booking ID válido, la etiqueta se descarga correctamente en PDF, y el primer evento de tracking llega a tu sistema sin intervención manual. Solo entonces tiene sentido pedir el cambio a producción, que DSV gestiona por correo directo: "When you have completed your development and tests you can request 'Go live' by sending an email to the API Support team via the Support page and specify which API(s) you are ready to go-live with".

Si tu operación incluye tramos internacionales por aire o mar, el mapeo de datos pasa por la Quote API en lugar de la de booking directa. la DSV Quote API es un servicio unificado que permite recibir cotizaciones para Air, Sea y freight enviando los detalles del envío, ideal para flujos de cotización digital dentro de tu sistema.

Fallo común: error de autorización por intercambiar las claves

Este es, con diferencia, el problema que más tickets de soporte genera en integraciones DSV. La documentación de AfterShip lo describe sin rodeos: la subscription key va en la cabecera HTTP, la access key va en el cuerpo de la petición, y mezclar las dos claves es la causa más común de errores de autorización.

La solución técnica es simple pero hay que forzarla en el código, no confiar en que el desarrollador se acuerde: separa explícitamente las dos variables en tu capa de integración (por ejemplo DSV_SUBSCRIPTION_KEY para el header y DSV_ACCESS_KEY para el body), y añade un test automatizado que falle de inmediato si detecta el patrón cruzado, antes de que la petición llegue siquiera a DSV. Te ahorra horas de depuración contra un error 401 genérico que no dice en ningún sitio "has puesto la clave donde no toca".

Hay un segundo fallo que no es un error de autenticación pero rompe procesos igual de rápido: para DSV Road Freight, DSV confirma la reserva pero no devuelve un archivo de etiqueta, así que hay que imprimir y aplicar tus propias etiquetas. Si tu flujo asume que toda confirmación trae etiqueta adjunta, se rompe silenciosamente en producción. Programa la generación local del PDF como paso separado cuando trabajes con este servicio concreto.

Cuándo construir la integración tú mismo y cuándo usar una capa multicarrier

Mantener credenciales, certificación y mapeos de campos para DSV por separado ya implica trabajo de mantenimiento continuo: cada cambio de versión en el portal, cada renovación de token, cada ampliación de cobertura geográfica exige revisión. Si tu empresa trabaja solo con DSV, construir la integración directa tiene sentido. Si trabajas con DSV junto a otros transportistas, el cálculo cambia: ahora multiplicas ese mantenimiento por cada proveedor.

Soluciones de conectividad multitransportista como Cargoson, MercuryGate, Descartes o Alpega exponen este tipo de integraciones, incluidas variantes como DSV Road y DSV Air & Sea, ya resueltas a través de un único API unificado para tu sistema. La diferencia práctica está en el tiempo de puesta en marcha: en lugar de pasar por certificación, aprobación de credenciales y pruebas de sandbox para cada transportista por separado, conectas una sola vez y añades proveedores según los vas incorporando a tu red.

Próximo paso

Si tu equipo ya tiene cuenta DSV Road o Contract Logistics activa, el primer movimiento concreto es registrar un usuario en el DSV Developer Portal y lanzar la solicitud de suscripción al producto correcto según tu modo de transporte dominante. Mientras esperas la aprobación de la access key en myDSV, aprovecha para mapear en tu TMS los campos obligatorios de la reserva (direcciones, dimensiones, peso, código HS si aplica) para no perder tiempo una vez llegue el acceso al sandbox.