¿Tienes un TMS o WMS propio? La API de DeCA se integra igual

Gran parte de las empresas que expiden mercancía no gestionan sus salidas en un ERP comercial, sino en un TMS propio, un WMS del almacén o un portal de expediciones desarrollado a medida. Es buena noticia para el DeCA: si tu sistema sabe cuándo sale un camión, sabe todo lo que el documento exige.

Y la buena noticia sigue: no necesitas ningún módulo concreto. La API de DeCA es REST estándar sobre HTTPS con JSON: cualquier sistema que pueda hacer una llamada HTTP con una cabecera X-API-Key puede emitir documentos. Sin instalar nada en tu infraestructura y sin depender del ciclo de versiones de un ERP.

El flujo, en cuatro pasos

1. Tu sistema decide la expedición. El TMS planifica la carga; el WMS confirma la salida del picking; el portal registra el envío. En ese momento, los datos del DeCA —cargador, mercancía, origen, destino, transportista, matrícula— ya existen en tu base de datos.
2. Una llamada emite el documento. POST /api/v1/deca_requests crea la recogida, abre el expediente y emite el DeCA con su QR y su PDF, todo en la misma petición. El campo source_reference guarda tu identificador interno: si la red falla y reintentas, no se emiten dos documentos para la misma expedición.
3. Tu sistema consulta el estado cuando quiera. El transportista cierra el documento escaneando el QR en la entrega; GET /api/v1/regulatory_records/:id/status te dice en qué punto está, sin intervención humana.
4. El PDF queda disponible por API o URL pública. Para adjuntarlo al expediente digital de tu TMS o entregárselo al cliente, GET …/pdf con la API key, o el enlace público por token.

Los endpoints que usarás (y los que no)

Para un flujo de expediciones estándar, cuatro llamadas cubren el ciclo completo: crear (POST /api/v1/deca_requests), consultar estado (GET …/status), descargar (GET …/pdf) y, si tu operativa agrupa entregas, crear rutas multi-parada con un DeCA agrupado (POST /api/v1/transport_routes — la Resolución de 5 de junio de 2026 lo admite y consume un solo cupo).

Lo que no se hace por API: dar de alta contrapartes (clientes de recogida y transportistas con contrato) ni maestros como direcciones, vehículos o catálogo de artículos — se gestionan una vez desde la web de la aplicación, y la API los lee. Es una decisión deliberada: los datos maestros cambian poco; las expediciones, todos los días.

Qué datos viajan en cada llamada (y por qué eso importa legalmente)

Un DeCA no es un PDF bonito: es una estructura de datos del artículo 6 de la Orden FOM/2861/2012. Cuando tu TMS llama a POST /api/v1/deca_requests, los campos del cuerpo de la petición se corresponden uno a uno con los apartados de esa estructura:

• Cargador contractual (nombre, NIF, domicilio): datos de los que responde el cargador según el artículo 7.2.
• Transportista efectivo (nombre, NIF): también responsabilidad del cargador, y el dato que más problemas da cuando hay subcontratación a última hora.
• Origen y destino, naturaleza y peso de la mercancía: los que ya tienes en tu pedido o en tu orden de expedición.
• Matrícula y fecha: responsabilidad del transportista efectivo (art. 7.3). El flujo habitual es emitir con el estado “pendiente de matrícula” y dejar que el conductor la añada al escanear el QR; si no lo hace, el documento se cierra automáticamente al terminar el día de emisión.

Esta separación no es un detalle técnico: es el mapa exacto de la exención del artículo 7.1. Si tu sistema emite el DeCA en el momento de la carga, tu empresa tiene registro de emisión con fecha y hora aunque el transportista no porte el documento, y la sanción es para él. Ningún flujo basado en papel o en correos te da esa prueba.

Errores habituales al integrar (y cómo evitarlos)

Tras acompañar integraciones de este tipo, estos son los puntos que más veces fallan:

• Reintentos sin idempotencia. Si la red cae a mitad de la llamada y tu sistema reintenta a ciegas, puedes emitir documentos duplicados. El campo source_reference existe precisamente para esto: con el mismo identificador interno, el reintento no crea un segundo documento.
• Datos maestros desactualizados. Si tu WMS tiene un NIF antiguo de un cliente de recogida, el documento se emitirá con ese dato — y la responsabilidad de su exactitud es del cargador. Valida los maestros antes de la primera emisión real.
• Emitir sin transportista efectivo conocido. Si tu operativa asigna el camión tarde, emite igualmente (queda pendiente de matrícula) en lugar de esperar; lo que no puedes es inventar un transportista y corregir después.
• No monitorizar el estado. Emitir y olvidarse funciona hasta que la inspección para el camión y el documento sigue abierto. Consulta el estado por API o activa avisos para saber qué documentos quedaron pendientes de matrícula al cierre del día.

Casos reales de sistemas a medida

• TMS de flota dedicada: al asignar la carga al vehículo, el TMS emite el DeCA y lo adjunta al viaje. El conductor solo ve el QR.
• WMS con expediciones propias: al confirmar el picking de salida, el WMS dispara la emisión; el PDF queda asociado a la ola de expedición.
• Portales B2B de cliente: si tus clientes registran sus envíos en un portal, el portal mismo puede emitir los DeCAs — el cargador legal sigue siendo tu cuenta, y la auditoría queda en tu plataforma.

¿Y si mi sistema es un ERP comercial?

Igual de cubierto: tenemos páginas específicas de integración para SAP, Odoo, Microsoft Dynamics 365 Business Central y Sage, con el flujo y los endpoints de cada uno. Y la referencia técnica completa, con ejemplo de código, está en la página de la API REST.

Cómo empezar

Activa el add-on API REST (50 €/mes o 480 €/año sobre cualquier plan de pago; incluida en Enterprise), genera tu API key en Mi Cuenta → pestaña API, y lanza tu primera emisión de prueba el mismo día. Si prefieres que analicemos tu TMS y te presupuestemos la integración llave en mano, escríbenos.

Preguntas frecuentes

¿La API emite el documento completo o solo avisa al transportista? Emite el documento completo: QR y PDF se generan en la misma petición. El transportista no necesita más que el QR para cerrar el documento con su matrícula.

¿Puedo emitir DeCAs para rutas con varias paradas desde mi TMS? Sí, con POST /api/v1/transport_routes: un documento agrupado por ruta, no uno por parada, y consume un solo cupo del plan.

¿Qué pasa si el transportista nunca escanea el QR? El documento se cierra automáticamente al terminar el día de emisión y queda constancia de que la matrícula estaba pendiente de su parte. Tu registro de emisión se mantiene intacto.

¿Necesito un plan concreto para la API? El add-on API REST se añade a cualquier plan de pago (el plan Free no admite add-ons) y viene incluido de serie en Enterprise.