Conecta tu programa con la API de DeCA5

Integra tu facturación, RR. HH., ERP o TMS con tus DeCA. Disponible en todos los planes, sin coste adicional por ahora; se mantienen los límites y las validaciones de tu plan. La versión 1 gestiona documentos de mercancías. Las hojas de ruta de viajeros se gestionan desde el portal.

Crear y gestionar mis claves Descargar OpenAPI 3 (JSON)

Dirección y autenticación

https://data5.es/api/deca5/v1

Un administrador crea las claves en «Mi plan → Conectar con tu programa». Guarda la clave en el servidor de tu aplicación: se muestra una sola vez. DeCA5 guarda su hash SHA-256. Puedes revocarla o rotarla desde el portal. Cada clave permite lectura, escritura o ambas; una clave de escritura no incluye lectura salvo que selecciones ambas.

curl 'https://data5.es/api/deca5/v1/consumo' \
+  -H "Authorization: Bearer $DECA5_API_KEY"

También se admite X-API-Key. Las peticiones con cuerpo llevan Content-Type: application/json. Máximo 64 KiB y 50 envíos por documento. El límite inicial es 120 llamadas por minuto y clave, configurable; las cabeceras X-RateLimit-Limit y X-RateLimit-Remaining indican el límite efectivo.

Operaciones v1

Método	Ruta desde /v1	Uso
GET	/consumo	Plan, límite mensual, documentos emitidos y restantes (mes de Madrid).
POST	/documentos	Crea un borrador. Con emitir: true también lo emite. Idempotency-Key obligatoria.
GET	/documentos	Lista con filtros desde, hasta, estado, cargador (id, NIF o nombre), conductor (id), matricula, limit y offset.
GET	/documentos/{id o numero}	Consulta un documento del cliente, incluido su estado y verificación.
POST	/documentos/{id}/emitir	Emite con las validaciones del portal, número, PDF y QR. Idempotency-Key obligatoria.
GET	/documentos/{id}/pdf	Descarga application/pdf, con las firmas y el sello de anulación si procede.
POST	/documentos/{id}/anular	Anula con motivo obligatorio. Idempotency-Key obligatoria. No devuelve cupo.
GET / POST	/{tipo}	Lista o crea cargadores, destinatarios, conductores o vehiculos. También transportistas, remolques y ubicaciones.
GET / PATCH / DELETE	/{tipo}/{id}	Consulta, modifica o da de baja una ficha. Las bajas conservan el historial.
GET	/maestros	Consulta los identificadores de todos tus maestros.
GET / POST	/webhooks	Lista o registra hasta 5 webhooks HTTPS. El secreto se muestra una vez.
DELETE	/webhooks/{id}	Desactiva un webhook y sus entregas pendientes.

Fechas: AAAA-MM-DD. Estados: borrador, emitido, sustituido o anulado. Listados de documentos: limit de 1 a 50 y offset de 0 a 10000. Maestros: buscar, inactivos=1 y limite de 1 a 2000. El listado de conductores oculta DNI y teléfono completos; los identificadores sirven para crear documentos.

Dar de alta y modificar fichas

Los campos de alta van dentro de datos. Para cambiar una ficha, envía cambios con PATCH. Cargadores y destinatarios: nombre, nif, direccion, codigo_postal, poblacion y provincia. Un cargador necesita dirección completa y puede darse de alta sin NIF; para emitir será obligatorio. Un destinatario necesita NIF válido. Conductores: nombre, dni_nie y telefono opcional. Vehículos: matricula. No se puede cambiar el DNI de un conductor; da de baja la ficha y crea la nueva.

curl -X POST 'https://data5.es/api/deca5/v1/cargadores' \
+  -H "Authorization: Bearer $DECA5_API_KEY" \
+  -H 'Content-Type: application/json' \
+  -d '{"datos":{"nombre":"Cargador ficticio","direccion":"Calle de prueba 1","codigo_postal":"09001","poblacion":"Burgos"}}'

curl -X PATCH 'https://data5.es/api/deca5/v1/cargadores/UUID_CARGADOR' \
+  -H "Authorization: Bearer $DECA5_API_KEY" \
+  -H 'Content-Type: application/json' \
+  -d '{"cambios":{"nif":"B12345674"}}'

El límite de conductores se comprueba también en el servidor. La API no compra ampliaciones ni bolsas; se gestionan desde el portal.

Crear un borrador y emitirlo

Las referencias se indican con un id propio o un dato natural: NIF, DNI o matrícula. Da de alta las fichas antes. Origen y destino también pueden ser texto. Todos los ejemplos usan datos ficticios y los UUID deben sustituirse por los de tus fichas.

curl -X POST 'https://data5.es/api/deca5/v1/documentos' \
+  -H "Authorization: Bearer $DECA5_API_KEY" \
+  -H 'Idempotency-Key: pedido-prueba-001' \
+  -H 'Content-Type: application/json' \
+  -d '{
    "referencia_externa":"PEDIDO-PRUEBA-001",
    "fecha_transporte":"2026-11-05",
    "cargador":{"id":"UUID_CARGADOR"},
    "transportista":{"id":"UUID_TRANSPORTISTA"},
    "conductor":{"id":"UUID_CONDUCTOR"},
    "vehiculo":{"id":"UUID_VEHICULO"},
    "envios":[{"origen":"Burgos","destino":"Madrid",
      "mercancias":[{"descripcion":"Mercancía ficticia","peso_kg":1000}]}]
  }'

La respuesta 201 contiene documento.id, estado borrador y número nulo. Un borrador sin NIF del cargador queda guardado. Al emitir se vuelve a consultar su ficha: completar el NIF permite emitir los borradores pendientes sin recrearlos.

curl -X POST 'https://data5.es/api/deca5/v1/documentos/UUID_DOCUMENTO/emitir' \
+  -H "Authorization: Bearer $DECA5_API_KEY" \
+  -H 'Idempotency-Key: emitir-pedido-prueba-001' \
+  -H 'Content-Type: application/json' -d '{}'

{
  "documento": {
    "id": "UUID_DOCUMENTO",
    "numero": "DECA-2026-00001",
    "estado": "emitido",
    "url_pdf": "https://data5.es/deca/TOKEN",
    "url_verificacion": "https://data5.es/deca/TOKEN/verificacion"
  }
}

La emisión exige los mismos datos del portal, incluido el NIF válido del cargador. Un 422 devuelve los datos pendientes. Para anular, POST a /documentos/UUID_DOCUMENTO/anular con {"motivo":"Transporte cancelado"} y otra Idempotency-Key.

Reintentos e idempotencia

Usa una Idempotency-Key distinta por operación (8–200 letras, números, dos puntos, guion o guion bajo). Si se pierde la respuesta, repite la misma ruta, clave y cuerpo exacto: se conserva el estado HTTP y el JSON y se devuelve Idempotency-Replayed: true. Reutilizarla con otro cuerpo o ruta devuelve 409. Las reservas pertenecen al cliente y siguen funcionando tras rotar las claves.

Los errores de validación también se conservan. Tras corregir los datos, usa una nueva Idempotency-Key. Si aparece en_curso tras un corte, consulta el documento y contacta con soporte para reconciliar la reserva; no lances otra creación con una clave nueva. No se caducan automáticamente las reservas inciertas. La referencia externa también evita crear otro documento con la misma referencia.

Webhooks firmados

curl -X POST 'https://data5.es/api/deca5/v1/webhooks' \
+  -H "Authorization: Bearer $DECA5_API_KEY" \
+  -H 'Content-Type: application/json' \
+  -d '{"url":"https://TU-DOMINIO.es/deca5/eventos","eventos":["deca.emitido","deca.anulado"]}'

Guarda el secreto recibido; solo se muestra una vez. Los eventos incluyen id, tipo, created_at y documento (id, número y estado), sin fichas ni contenido del transporte. Se notifican también los cambios realizados desde el portal o Lola. Para cambiar el secreto, crea otro webhook y desactiva el anterior.

{
  "id": "UUID_EVENTO",
  "tipo": "deca.emitido",
  "created_at": "2026-11-05T08:00:00Z",
  "documento": {
    "id": "UUID_DOCUMENTO",
    "numero": "DECA-2026-00001",
    "estado": "emitido"
  }
}

Verifica X-DeCA5-Signature: v1= seguido del HMAC-SHA256 hexadecimal de timestamp + "." + cuerpo HTTP original, usando el secreto. El timestamp llega en X-DeCA5-Timestamp (segundos Unix). Compara en tiempo constante, rechaza una antigüedad superior a 5 minutos y deduplica por X-DeCA5-Event-Id. La firma cambia en cada intento.

Responde 2xx dentro de 10 segundos. La entrega es al menos una vez; no se garantiza orden entre eventos. Hasta 8 intentos, con esperas de 1, 5, 15, 60, 180, 360 y 720 minutos más la cadencia del procesador. Redirecciones y destinos privados no se admiten. Una entrega agotada se consulta por soporte; consulta siempre el estado actual del documento.

Errores y diagnóstico

{
  "error": {
    "codigo": "ambito_no_permitido",
    "mensaje": "La clave no tiene ámbito de escritura"
  }
}

400: JSON o Idempotency-Key no válidos. 401: clave no válida o revocada. 403: ámbito insuficiente, cuenta o API inactiva, o tipo de transporte no soportado. 404: recurso inexistente. 409: conflicto, límite del plan o petición en curso. 413: cuerpo demasiado grande. 422: validación. 429: demasiadas llamadas; respeta Retry-After. 503: servicio no disponible o resultado pendiente; consulta antes de repetir una operación.

Conserva X-Request-Id para soporte. El registro de llamadas guarda identificadores técnicos, ruta normalizada, duración y estado HTTP; no incluye claves, cuerpos, consultas ni fichas personales. Cada petición obtiene el cliente de su clave; no se admite cliente_id en el cuerpo.