Cómo integrar tu ERP con DeCA: del albarán al documento emitido

Desde el 5 de octubre de 2026, el DeCA (Documento electrónico de Control Administrativo) es obligatorio y exclusivamente digital para el transporte público de mercancías por carretera (Ley 9/2025, Disposición Transitoria 8ª). Y desde esa fecha, hay una pregunta que muchas empresas con ERP se hacen: si mi sistema ya conoce cada expedición, ¿por qué tengo que volver a teclearla en otra herramienta?

La respuesta corta: no tienes que hacerlo. La API REST de DeCA existe justo para eso.

El problema de la doble captura de datos

El DeCA exige datos que tu ERP ya tiene: quién es el cargador, qué mercancía viaja (descripción, naturaleza, peso, bultos), de dónde sale, a dónde va, qué transportista la lleva y con qué vehículo. Son los mismos datos del albarán, de la orden de transporte o del pedido de venta.

Cuando la emisión del DeCA se hace a mano, cada expedición se teclea dos veces: una en tu ERP y otra en la plataforma. El resultado es predecible:

• Tiempo perdido: minutos por expedición, multiplicados por decenas de salidas diarias.
• Erratas: un NIF mal tecleado o un peso incorrecto son justamente lo que una inspección detecta.
• Olvidos: la prisa del muelle hace que alguna expedición salga sin documento. Y la multa por transporte sin DeCA va de 401 a 600 € por envío (LOTT, art. 141.17 y 143.1.d), no por empresa.

Además, el responsable de generar el documento es el cargador (art. 7.2 de la Orden FOM/2861/2012). Si tu empresa expide mercancía, el DeCA es tu obligación, no la del transportista.

Cómo funciona la integración por API

La API de DeCA es REST sobre HTTPS, devuelve JSON y se autentica con una cabecera X-API-Key. No necesita ningún software intermedio: cualquier sistema capaz de hacer una llamada HTTP puede emitir DeCAs.

El caso más simple cabe en una sola llamada: POST /api/v1/deca_requests. Envías los datos de la expedición y, con emit: true, el documento sale emitido en la misma petición:

curl -X POST https://app.deca.cangopal.com/api/v1/deca_requests \
  -H "X-API-Key: TU_CLAVE" -H "Content-Type: application/json" \
  -d '{
    "legal_shipper_id": "…",
    "reference": "EXP-2026-0043",
    "source_reference": "ERP-8843",
    "pickup_client_id": "…",
    "planned_pickup": "2026-10-05T09:30:00+02:00",
    "emit": true,
    "deca": {
      "locations": { "unloading_place": { "street": "ZAL 1, Muelle 4", "city": "Barcelona", "postal_code": "08040", "country": "ES" } },
      "transport_means": { "tractor_plate": "1234ABC" },
      "goods_items": [ { "description": "Componentes electrónicos", "gross_weight_kg": 250, "quantity": 15, "package_type": "cajas" } ]
    }
  }'

La respuesta devuelve el identificador del expediente, el token público del documento y la URL de descarga del PDF. Tu sistema guarda esos tres datos junto a la expedición, y el transportista cierra el DeCA escaneando el QR con su móvil.

Tres detalles que marcan la diferencia en un entorno real:

• Reintentos idempotentes: la pareja sistema-origen + referencia es única. Si la red falla después de emitir y reenvías la misma llamada, no se duplica el documento.
• Emisión atómica: la llamada es una transacción. Si algo falla, no queda ni recogida ni borrador a medias.
• Rutas multi-parada: si cargas una vez y entregas en varios destinos, se crea una ruta con sus paradas y se emite un único DeCA agrupado, tal como admite la Resolución de 5 de junio de 2026. Consume un solo cupo del plan, no una unidad por parada.

¿Y mi ERP concreto?

La API es estándar, pero cada ERP tiene su manera de lanzar la llamada. Hemos preparado páginas específicas con el enfoque de cada uno:

• Integrar DeCA con SAP — para quien expide desde la salida de mercancía de un ERP de gran empresa, con flotas y transportistas habituales.
• Integrar DeCA con Odoo — el caso del albarán de entrega validado en Odoo que emite su documento, sin conector de marketplace.
• Integrar DeCA con Microsoft Dynamics 365 Business Central — envíos y transferencias entre centros, con extensiones AL o Power Automate.
• Integrar DeCA con Sage — la gestión comercial de la pyme española que expide mercancía cada día.
• API REST de DeCA — para TMS propios, WMS, portales a medida o cualquier otro sistema. Y si ese es tu caso, tenemos un artículo completo sobre cómo se integra DeCA con un TMS o WMS propio, junto al checklist descargable de integración para tu equipo de IT.

En todas ellas encontrarás los endpoints principales, casos de uso y las preguntas frecuentes de cada integración.

Qué necesitas para empezar

1. Una cuenta en DeCA (registro gratuito, sin permanencia).
2. El add-on API REST: 50 €/mes (o 480 €/año con el descuento anual) sobre cualquier plan base de pago. En el plan Enterprise va incluido.
3. Tu API key: se genera en Mi Cuenta → pestaña API y solo se muestra una vez.

Los DeCAs emitidos por API comparten el límite mensual de tu plan con los creados desde la web: mismo contador, sin sorpresas.

¿Quién desarrolla la integración?

Dos caminos válidos:

• Tu equipo o tu integrador habitual, con la documentación técnica de la API (disponible en la aplicación, en la sección de documentación para integradores). Si tu equipo ya ha conectado el ERP con un transportista o un marketplace, esta integración es más simple que esas.
• CANGOPAL la desarrolla por ti. Tenemos experiencia en integraciones con SAP, Microsoft Dynamics, Sage y Odoo. Escríbenos a support@cangopal.com, cuéntanos qué ERP usas y te presupuestamos el desarrollo.

Qué datos devuelve la API tras emitir (y para qué sirven)

La respuesta de la emisión no es un simple “OK”: devuelve tres datos que tu ERP debe guardar junto a la expedición:

• Identificador del expediente en la plataforma: tu clave para consultas posteriores por API (estado, documentos, registros).
• Token público del documento: es lo que hay detrás del QR. Si tu portal de clientes o tu TMS quiere enlazar el DeCA, enlaza esa URL.
• URL de descarga del PDF: para adjuntarlo al expediente digital de la expedición o enviárselo al cliente con el albarán.

Con esos tres datos, el ciclo se cierra sin fricción: tu sistema emite, guarda la referencia, y consulta el estado cuando le interese —por ejemplo, al cierre del día, para detectar los documentos que quedaron pendientes de matrícula y avisar al transportista antes de que el cierre automático los definitiva.

Gestión de errores: lo que tu integración debe contemplar

Una integración robusta no es la que nunca falla, sino la que sabe qué hacer cuando algo falla. Los casos que debes contemplar:

• Credenciales inválidas (401): la API key es incorrecta o se revocó. Tu sistema debe avisar a un humano, no reintentar en bucle.
• Datos inválidos (422): falta un campo obligatorio del artículo 6 o el formato es incorrecto. La respuesta detalla qué campo falla; registra ese error con la referencia de la expedición para corregir el dato en origen.
• Conflicto de referencia (409): ya existe una expedición con esa source_reference. Casi siempre significa que un reintento llegó después de que la primera llamada triunfara: consulta el estado en lugar de crear otra.
• Timeout sin respuesta: el caso más delicado. Como no sabes si la emisión llegó a producirse, reintenta con la misma source_reference; la idempotencia garantiza que no habrá duplicado, y la respuesta te dice el estado real del documento.

Ninguno de estos casos exige lógica exótica: son los mismos patrones de cualquier API REST. Pero conviene decidirlos antes de la primera emisión real, no durante un control de carretera.

Preguntas frecuentes

¿Puedo emitir DeCAs desde varios sistemas a la vez? Sí: cada llamada es independiente y el source_reference distingue el sistema de origen. Puedes emitir desde el ERP las ventas y desde el WMS las salidas de almacén sin que se pisen.

¿Los documentos por API consumen cupo del plan igual que los manuales? Sí, comparten el mismo contador mensual del plan. La API no es una tarifa oculta: es una forma más de emitir dentro de tu plan.

¿Puedo probar la integración sin emitir documentos reales? Sí: crea la recogida sin emit: true y verás el flujo completo de datos sin consumir cupo. Cuando el flujo esté validado, activa la emisión.

¿Cuánto cuesta el desarrollo? Depende de tu ERP y de quién lo haga. Con la documentación de la API, un equipo que ya haya integrado el ERP con un transportista lo resuelve en días. Si prefieres presupuesto llave en mano, escríbenos con el nombre de tu ERP y tu volumen aproximado de expediciones.

En resumen

Si tu empresa expide mercancía por carretera, el DeCA es obligatorio desde el 5 de octubre de 2026. Si además gestionas esas expediciones en un ERP, emitir el documento a mano es la peor de las opciones: lenta, propensa a errores y difícil de auditar. La integración por API convierte un dato que tu sistema ya tiene en un documento válido, con su QR, su PDF y su registro de auditoría, sin que nadie teclee nada dos veces.