Digitaldocu · Integración

API del DeCA

Para emitir documentos electrónicos de control administrativo desde tu propio sistema de gestión, sin teclear nada dos veces.

1Qué hace y qué no

Mandas los datos del transporte. Nosotros componemos el DeCA en PDF, le estampamos el código QR, le incrustamos los datos estructurados eFTI, lo firmamos digitalmente si tu suscripción tiene firma, lo archivamos en tu Digitaldocu y avisamos al conductor.

Te devolvemos su número de expedición y su identificador. A partir de ahí el documento vive en tu Digitaldocu como cualquier otro.

2Cargador o transportista

Un DeCA nombra siempre a las dos partes, así que la API pide los datos de las dos vengas de donde vengas. Lo que cambia es cuáles son tuyos:

3Tu clave

Se crea desde el panel, en Claves para tu programa. Se enseña una sola vez: guárdala en cuanto la veas, porque ni nosotros podemos volver a mostrarla. Si se pierde, se revoca y se crea otra.

Authorization: Bearer deca_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

La clave identifica tu suscripción por sí sola: no hay que mandar ningún otro dato para decir quién eres. Solo sirve para lo que hay en este documento — no da acceso al resto de tus documentos de Digitaldocu.

4Crear una expedición

Obligatorios

Son los que exige la norma (Orden FOM/2861/2012, art. 6). Si falta alguno no se emite nada y te decimos cuáles. Los de tu propia empresa puedes omitirlos si los has guardado en el panel (ver el punto 2).

Opcionales

No emitas dos veces lo mismo

Manda tu propia referencia en la cabecera Idempotency-Key —tu número de expedición sirve—. Si repites la llamada porque se te cayó la red y no viste la respuesta, te devolvemos el mismo documento en vez de emitir otro.

curl -X POST https://deca.digitaldocu.es/api/deca/v1/expediciones \
  -H "Authorization: Bearer $DECA_KEY" \
  -H "Idempotency-Key: ALB-2026-000123" \
  -H "Content-Type: application/json" \
  -d '{
    "cargador": "INDUSTRIAS EJEMPLO, S.L.",
    "cargador_nif": "B00000000",
    "cargador_domicilio": "Calle Ejemplo 1, Valencia",
    "transportista": "TRANSPORTES EJEMPLO, S.L.",
    "transportista_nif": "B11111111",
    "origen": "Valencia",
    "destino": "Madrid",
    "fecha": "2026-08-25",
    "mercancia": "Palés de mercancía general",
    "peso": "17,00 Tn",
    "matricula": "1234BCD",
    "conductor": "Juan Ejemplo",
    "movil": "600000000"
  }'

201 Created

{ "ok": true,
  "documentId": 123456,
  "expedicion": "DECA-20260825-A1B2C3" }

Si repites con la misma Idempotency-Key:

{ "ok": true, "repetida": true,
  "documentId": 123456,
  "expedicion": "DECA-20260825-A1B2C3" }

5Adjuntar tu albarán

Para colgar del DeCA el documento de origen: tu albarán, tu CMR, el tique de báscula. Queda enlazado al DeCA y no se lo enseñamos al destinatario salvo que alguien lo comparta a mano desde el panel — suele llevar datos del cargador que el receptor no tiene por qué ver.

curl -X POST \
  "https://deca.digitaldocu.es/api/deca/v1/expediciones/DECA-20260825-A1B2C3/adjuntos" \
  -H "Authorization: Bearer $DECA_KEY" \
  -F "tipo=albaran" \
  -F "file=@albaran-000123.pdf"

Valores de tipo: albaran, cmr, foto_carga, ticket_bascula, packing_list, otros.

6Consultar el estado

{ "ok": true,
  "expedicion": "DECA-20260825-A1B2C3",
  "documentId": 123456,
  "estado": "En tránsito",
  "entregado": false,
  "fechaFirma": null,
  "matricula": "1234BCD",
  "conductor": "Juan Ejemplo",
  "origen": "Valencia",
  "destino": "Madrid",
  "adjuntos": 1,
  "enlace": "https://backend.digitaldocu.com/api/Documents/Share/…" }

El enlace es el mismo al que apunta el QR del documento. Caduca, así que no lo guardes: pídelo cuando lo necesites.

7Que te avisemos al entregar

En vez de preguntar cada poco por cada expedición, dinos una dirección y te llamamos nosotros cuando el destinatario firma. Se configura en el panel, en Avisar a tu sistema.

POST https://erp.tuempresa.com/webhooks/deca
X-DeCA-Evento: entrega_firmada
X-DeCA-Firma:  sha256=a1b2c3…

{ "evento": "entrega_firmada",
  "documentId": 123456,
  "expedicion": "DECA-20260825-A1B2C3",
  "matricula": "1234BCD",
  "firmado_at": "2026-08-25 14:32",
  "firmante": "Ana Ejemplo",
  "firmante_nif": "00000000T",
  "incidencias": null,
  "observaciones": null }

Comprueba que el aviso es nuestro

La cabecera X-DeCA-Firma es el HMAC-SHA256 del cuerpo, con el secreto que verás en el panel al configurar la dirección. Compáralo antes de fiarte del mensaje:

# Python
import hmac, hashlib
esperado = "sha256=" + hmac.new(
    SECRETO.encode(), cuerpo_en_bruto, hashlib.sha256
).hexdigest()
if not hmac.compare_digest(esperado, cabecera_firma):
    return 401

• Contesta con un 2xx. Cualquier otra cosa la tomamos por fallo.
• Si no contestas, reintentamos a 1, 5 y 30 minutos, y a las 2 y 12 horas.
• Un aviso por entrega. Aunque la recepción se confirme dos veces, tú recibes uno.
• La dirección tiene que ser https y con nombre de dominio. No admitimos direcciones IP ni nombres de red interna.

8Errores

Cuando faltan datos te decimos exactamente cuáles, para que puedas programar contra ello:

400 Bad Request

{ "error": "faltan datos obligatorios del DeCA",
  "code": "campos_incompletos",
  "faltan": ["cargador_nif", "origen", "peso"],
  "avisos": [
    { "campo": "cargador_nif",
      "nivel": "falta",
      "motivo": "obligatorio: no viene en la petición" }
  ] }

9Límites