¿Los DeCA emitidos por API cuentan en el plan?

Los DeCA creados por API con datos estructurados se tratan como DeCA manuales: ilimitados en todos los planes. Solo cuentan los generados a partir de una foto.

¿Qué pasa si envío dos veces la misma petición?

Se emiten dos DeCA: la API no deduplica. Guarda el id que devuelve cada 201 en tu expedición y no reintentes una petición ya aceptada. Si emites uno de más, anúlalo con /cancel; queda registrado, nada se borra.

¿Puedo obtener el PDF y la URL pública por API?

Sí. La respuesta de creación y de consulta incluye el identificador DECA-AAAA-NNNNNN, la URL pública del documento y la URL de descarga directa del PDF, que es la que va en el QR.

API para emitir el DeCA desde tu ERP o TMS

Para qué sirve la API

Si tu empresa ya tiene los datos del servicio en un ERP, un TMS o una hoja de cálculo bien organizada, no necesitas que nadie haga una foto: tu sistema puede emitir el DeCA directamente cuando se planifica el viaje. La API de DeCA Fast expone la misma emisión que usan el bot y el panel, con las mismas reglas: PDF nativo con QR, URL única, hora de emisión del servidor, snapshot de transportista y matrículas, inmutabilidad y sustitución.

Casos típicos:

Emitir el DeCA al confirmar la orden de carga en el TMS y enviar el PDF al conductor por vuestro canal.
Sustituir el DeCA automáticamente cuando tráfico cambia el vehículo asignado.
Descargar los DeCA del mes para archivarlos junto a las facturas.
Una gestoría que emite para varios clientes desde su propio software, con una clave por empresa.

Los DeCA emitidos por API con datos estructurados son ilimitados y no cuentan en el plan; solo cuentan los generados a partir de una foto.

Autenticación

Cada empresa crea sus claves desde el panel (sección API). La clave se muestra una sola vez; guárdala en tu gestor de secretos. Se envía en cada petición:

Authorization: Bearer dfk_live_xxxxxxxxxxxxxxxx

La clave está acotada a tu empresa: todo lo que crees o consultes pertenece a ella. Puedes tener varias claves (una por sistema) y revocarlas por separado.

Base de la API: https://decatransporte.ai/api/v1. Todas las respuestas son JSON.

Crear un DeCA

POST /api/v1/deca

{
  "vehicle_id": "5f0c…",
  "cargador_nombre": "Embutidos Ejemplo SL",
  "cargador_nif": "B17000000",
  "cargador_domicilio": "Pol. Ind. La Selva 12, 17430 Santa Coloma de Farners",
  "origen_empresa": "Embutidos Ejemplo SL",
  "origen_direccion": "Pol. Ind. La Selva 12, Santa Coloma de Farners",
  "destino_empresa": "Mercabarna",
  "destino_direccion": "Nave 3, 08040 Barcelona",
  "mercancia_descripcion": "Embutido curado, 4 palés",
  "mercancia_peso": "1200 kg",
  "fecha_servicio": "2026-10-06",
  "observaciones": null,
  "autorizacion_especial": null
}

Campo	Obligatorio	Notas
`vehicle_id`	Sí	El vehículo, dado de alta en el panel. Las matrículas salen de ahí; no se envían en el body.
`cargador_nombre`, `cargador_nif`, `cargador_domicilio`	Sí	Cargador contractual, no el dueño de la mercancía si hay intermediario (subcontratación).
`origen_direccion`, `destino_direccion`	Sí	Dirección del lugar de carga y de entrega, texto libre.
`origen_empresa`, `destino_empresa`	No	Empresa o nombre del lugar. Aparece encima de la dirección en el PDF.
`mercancia_descripcion`, `mercancia_peso`	Sí	Peso como texto (`"1200 kg"`, `"4 palés"`).
`fecha_servicio`	Sí	`AAAA-MM-DD`. Se acepta también `DD-MM-AAAA` y `DD/MM/AAAA`; se guarda siempre como `AAAA-MM-DD`.
`observaciones`, `autorizacion_especial`	No	Artículo 6 h) y e).
`phone`	No	Teléfono del conductor vinculado, solo para dejar constancia de quién originó el DeCA. No determina el vehículo.

Transportista efectivo (nombre, NIF) no se envía: se toma del perfil de la empresa dueña de la clave, para que no pueda emitirse un DeCA a nombre de otro.

La API comprueba que todos los campos obligatorios estén informados, pero no valida el formato del NIF del cargador: el dato es responsabilidad de tu sistema. Y cada llamada emite un DeCA nuevo: no hay deduplicación, así que no reintentes una petición que ya ha devuelto 201.

Respuesta 201 Created:

{
  "id": "9b1e…",
  "numero": "DECA-2026-000123",
  "estado": "emitido",
  "emitido_at": "2026-10-06T08:42:11Z",
  "url": "https://decatransporte.ai/d/…",
  "pdfUrl": "https://decatransporte.ai/d/…/pdf"
}

pdfUrl es la descarga directa del PDF, la que debe ir en cualquier QR o enlace que generes por tu cuenta. url es la página del documento.

Consultar

GET /api/v1/deca/{id} devuelve todos los datos del DeCA, su estado, las URLs y, si aplica, a qué documento sustituye o por cuál ha sido sustituido.

GET /api/v1/deca?from=2026-10-01&to=2026-10-31&estado=emitido&cursor=… lista paginada por fechas y estado. Útil para archivado mensual y para conciliar con tu facturación.

Sustituir (modificación en ruta)

POST /api/v1/deca/{id}/replace

{
  "motivo": "Cambio de vehículo por avería",
  "vehicle_id": "a71d…",
  "changes": { "destino_direccion": "Nave 5, 08040 Barcelona" }
}

Crea un DeCA nuevo con los datos del original más los cambios, nuevo número, nueva URL y nuevo QR, enlazado al anterior. El original pasa a sustituido y sigue accesible. Es la vía 2 del apartado quinto de la Resolución de 5 de junio de 2026 (modificar el DeCA). motivo es obligatorio y aparece en ambos documentos. Recuerda hacer llegar el nuevo PDF al conductor: la norma lo exige.

Anular

POST /api/v1/deca/{id}/cancel con { "motivo": "Servicio cancelado por el cliente" }. Para servicios que no llegaron a realizarse. El DeCA queda anulado, se conserva y su URL muestra el aviso. Nada se borra.

Errores

Formato estable:

{ "error": { "code": "missing_required_field", "message": "Faltan campos obligatorios", "fields": ["destino_direccion"] } }

Código	HTTP	Significado
`missing_key` / `invalid_key`	401	Sin clave o clave revocada.
`validation_error`	400	Body mal formado (JSON, UUID, falta `vehicle_id`). `fields` indica cuáles.
`missing_required_field`	422	Falta un dato del artículo 6 o `fecha_servicio` no es `AAAA-MM-DD`. No se emite; `fields` lista los que faltan.
`no_vehicle`	409	El `vehicle_id` no existe o no pertenece a tu empresa.
`not_found`	404	El DeCA no existe o no es de tu empresa.
`rate_limited`	429	Más de 60 peticiones por minuto con la misma clave.

Límites y garantías

60 peticiones por minuto por clave. Suficiente para emitir en tiempo real; para cargas masivas, espacia las llamadas.
Sin deduplicación: cada POST /deca que devuelve 201 es un DeCA nuevo. Guarda el id que recibes y no reintentes peticiones ya aceptadas.
Sin borrado: todo DeCA emitido, sustituido o anulado se conserva y su URL sigue activa.
Hora del servidor: emitido_at es la hora real de emisión. No se puede antedatar. Si tu sistema emite después de la salida del camión, el DeCA será tarde; emite al confirmar la carga, no al facturar.

Qué no hace la API hoy

No expone la lectura de fotos ni de audios: eso es el bot. Si quieres emitir desde una foto o un audio, el conductor lo envía por WhatsApp.
No hay webhooks de salida (aviso a tu sistema cuando un conductor emite). Está previsto; mientras tanto, el listado paginado permite sincronizar.
No agrupa varios envíos en un DeCA. Un envío, una llamada.

¿Integración concreta o dudas sobre el contrato? Escríbenos. Si eres gestoría, mira también DeCA Fast para gestorías.

API de DeCA Fast