Documentación de la API DeCA

Completar un DeCA por un tercero

Si a tu ERP le faltan datos que conoce otra empresa —por ejemplo, la matrícula que asignará el transportista o la localidad exacta de descarga—, puedes crear el DeCA igualmente y pedir esos datos a un tercero. Es la misma función «Completar por la contraparte» de la web: el tercero recibe un email con un enlace seguro, rellena solo los campos que le pides y, cuando ya no falta ningún dato obligatorio, el DeCA se genera automáticamente y pasa a vigente, con su PDF, su QR y su URL de verificación. Requiere el mismo acceso que el resto de la API (plan Business con el complemento API activo).

Añade completionRequest al cuerpo de POST /api/v1/decas, con el email del destinatario (recipientEmail) y los campos que debe completar (fields). Esos campos pueden llegar vacíos; todos los demás deben ser válidos, igual que en una creación normal. La respuesta es 202 Accepted con un borrador (object: "deca_draft"), no con un DeCA vigente. Opcionalmente: recipientName, recipientType (shipper | carrier | authorized_person) y expiresInHours (1–48; por defecto 24).

Igual que en la web, solo se pueden pedir las matrículas y los datos de descarga: el lugar de carga, la provincia, el país, las partes, la mercancía y el peso los aporta siempre quien crea el DeCA (si no, la API responde 422 invalid_completion_field).

{
  "externalId": "TR-45882",
  "loadDate": "06-10-2026",
  "unloadDate": "07-10-2026",
  "vehicle": {
    "tractorPlate": "",
    "trailerPlate": ""
  },
  "shipper": {
    "name": "CERÁMICAS DEL MEDITERRÁNEO S.A.",
    "taxId": "A12345674",
    "country": "ES",
    "address": "Carretera de Alcora km 3",
    "postalCode": "12006",
    "city": "Castellón de la Plana"
  },
  "carrier": "self",
  "shipments": [
    {
      "loadLocation": {
        "name": "Planta 1",
        "address": "Carretera de Alcora km 3",
        "postalCode": "12006",
        "city": "Castellón de la Plana",
        "country": "ES"
      },
      "unloadLocation": {
        "name": "Almacenes Norte",
        "address": "Polígono Arasur, calle C 14",
        "postalCode": "01230",
        "city": "",
        "country": "ES"
      },
      "goods": "Azulejo cerámico en palés",
      "weight": 18400
    }
  ],
  "completionRequest": {
    "recipientEmail": "operaciones@transportista.example",
    "recipientType": "carrier",
    "fields": [
      "vehicle.tractorPlate",
      "vehicle.trailerPlate",
      "shipments[0].unloadLocation.city"
    ]
  }
}

{
  "id": "cmupjfyb600uvvos0tycclmsp",
  "object": "deca_draft",
  "status": "pending_completion",
  "decaId": null,
  "externalId": "TR-45882",
  "missingFields": [
    "shipments[0].unloadLocation.city",
    "vehicle.tractorPlate"
  ],
  "createdAt": "2026-10-01T14:56:31+02:00",
  "updatedAt": "2026-10-01T14:56:31+02:00",
  "completionRequest": {
    "id": "cmupjfybh00uxvos0uwlt3pjv",
    "status": "pending",
    "requestedFields": [
      "shipments[0].unloadLocation.city",
      "vehicle.tractorPlate",
      "vehicle.trailerPlate"
    ],
    "recipientEmail": "operaciones@transportista.example",
    "createdAt": "2026-10-01T14:56:31+02:00",
    "expiresAt": "2026-10-02T14:56:31+02:00",
    "completedAt": null
  },
  "warnings": []
}

El enlace seguro

El enlace se envía solo por email al destinatario; la API nunca lo devuelve. Es personal, de un solo uso y caduca a las expiresInHours horas. El tercero no necesita cuenta, solo ve el nombre de tu empresa y los campos que le pides, y no puede modificar ningún otro dato. El email indica qué empresa solicita los datos, la fecha de caducidad y qué ocurre al enviarlos.

Cuando el tercero completa los datos

Los datos se validan y se incorporan al borrador. Si ya no falta ningún dato obligatorio, el DeCA se genera automáticamente con tu integración como autora ( conserva tu externalId), el borrador pasa a issued y su decaId es el DeCA vigente; el tercero recibe una copia por email. Si aún faltan datos, el borrador queda en draft y missingFields te dice cuáles.

Consultar el estado

GET /api/v1/decas/{id} responde tanto con el id del borrador como con el del DeCA ya emitido (que también incluye completionRequest). Estados del borrador:

• pending_completion — Hay una solicitud abierta: el tercero aún no ha enviado los datos.
• draft — Faltan datos (missingFields) y no hay ninguna solicitud abierta: pide los datos o reenvía.
• ready — No falta nada, pero el DeCA no se pudo emitir (por ejemplo, cupo del plan agotado). Se puede emitir desde el panel.
• issued — El DeCA ya es vigente: consúltalo con decaId.
• cancelled — El borrador se canceló desde el panel.

completionRequest.status: pending, completed, expired o replaced (sustituida por un reenvío).

{
  "id": "cmupjfyb600uvvos0tycclmsp",
  "object": "deca_draft",
  "status": "issued",
  "decaId": "cmupjfyzn00vzvos06903zz7y",
  "externalId": "TR-45882",
  "missingFields": [],
  "createdAt": "2026-10-01T14:56:31+02:00",
  "updatedAt": "2026-10-01T14:56:32+02:00",
  "completionRequest": {
    "id": "cmupjfynd00vmvos07hmyqdfy",
    "status": "completed",
    "requestedFields": [
      "shipments[0].unloadLocation.city",
      "vehicle.tractorPlate",
      "vehicle.trailerPlate"
    ],
    "recipientEmail": "operaciones@transportista.example",
    "createdAt": "2026-10-01T14:56:32+02:00",
    "expiresAt": "2026-10-02T14:56:32+02:00",
    "completedAt": "2026-10-01T14:56:32+02:00"
  }
}

{
  "id": "cmupjfyb600uvvos0tycclmsp",
  "object": "deca_draft",
  "status": "draft",
  "decaId": null,
  "externalId": "TR-45882",
  "missingFields": [
    "shipments[0].unloadLocation.city",
    "vehicle.tractorPlate"
  ],
  "createdAt": "2026-10-01T14:56:31+02:00",
  "updatedAt": "2026-10-01T14:56:31+02:00",
  "completionRequest": {
    "id": "cmupjfybh00uxvos0uwlt3pjv",
    "status": "expired",
    "requestedFields": [
      "shipments[0].unloadLocation.city",
      "vehicle.tractorPlate",
      "vehicle.trailerPlate"
    ],
    "recipientEmail": "operaciones@transportista.example",
    "createdAt": "2026-10-01T14:56:31+02:00",
    "expiresAt": "2026-10-01T14:56:30+02:00",
    "completedAt": null
  }
}

Pedir los datos después

También puedes crear primero el borrador ("draft": true en lugar de completionRequest) y pedir los datos más tarde. Si ya hay una solicitud pendiente, la respuesta es 409 completion_request_pending; si el DeCA ya es vigente, 409 deca_already_issued (usa una corrección).

{
  "recipientEmail": "operaciones@transportista.example",
  "fields": [
    "vehicle.tractorPlate",
    "shipments[0].unloadLocation.city"
  ],
  "expiresInHours": 48
}

{
  "id": "cmupjfyhp00v8vos059cdhihy",
  "completionRequest": {
    "id": "cmupjfyij00vcvos0ga6ikvio",
    "status": "pending",
    "requestedFields": [
      "shipments[0].unloadLocation.city",
      "vehicle.tractorPlate"
    ],
    "recipientEmail": "operaciones@transportista.example",
    "createdAt": "2026-10-01T14:56:31+02:00",
    "expiresAt": "2026-10-03T14:56:31+02:00",
    "completedAt": null
  }
}

Reenviar la solicitud

POST /api/v1/decas/{id}/completion-request/resend envía un enlace nuevo al mismo destinatario con los campos que aún no se han completado; el enlace anterior deja de funcionar. Úsalo, por ejemplo, cuando el enlace ha caducado. Cuerpo opcional: { "expiresInHours": 24 }. Máximo 5 reenvíos por borrador y hora; una solicitud ya completada responde 409 completion_request_completed.

{
  "id": "cmupjfyb600uvvos0tycclmsp",
  "completionRequest": {
    "id": "cmupjfynd00vmvos07hmyqdfy",
    "status": "pending",
    "requestedFields": [
      "shipments[0].unloadLocation.city",
      "vehicle.tractorPlate",
      "vehicle.trailerPlate"
    ],
    "recipientEmail": "operaciones@transportista.example",
    "createdAt": "2026-10-01T14:56:32+02:00",
    "expiresAt": "2026-10-02T14:56:32+02:00",
    "completedAt": null
  }
}

Seguridad e idempotencia

Una credencial solo ve y gestiona los borradores de su propia integración (con deca:read_company, puede leer todos los de su empresa). Todas estas llamadas exigen Idempotency-Key: si repites una con la misma clave, recibes la misma respuesta (200, Idempotent-Replayed: true) sin crear otro borrador, otra solicitud ni otro email. Cada paso queda registrado: quién lo pidió, cuándo se abrió el enlace, quién completó qué y cuándo se generó el DeCA.

Borradores: varios transportes a la vez

Si tu sistema prepara varios transportes en paralelo, abre un borrador por cada uno con POST /api/v1/drafts. Cada borrador es independiente y tiene su propio draftId: puedes tener todos los que necesites abiertos a la vez, completarlos poco a poco y generar cada DeCA cuando esté listo, sin que un borrador pise a otro. Un borrador no consume cuota de tu plan; la cuota se consume solo al generar el DeCA definitivo.

El cuerpo es el mismo que el de POST /api/v1/decas, pero puede estar incompleto. Cada respuesta indica ready y, si falta algo, issues con los mismos detalles de error que daría la creación directa.

Los borradores abiertos también aparecen en la web, en Mis DeCA › Borradores pendientes (con la etiqueta «API» y tu externalId), para los usuarios de tu empresa que pueden crear DeCA. Desde allí se pueden continuar en el asistente, generar o descartar. Si se genera desde la web, el borrador queda generated con su decaId (y generatedByApiCredentialId vacío); si se descarta, queda cancelled. Consúltalo con GET /api/v1/drafts/{id}.

{
  "externalId": "VIAJE-4471",
  "reference": "Pedido 88231",
  "loadDate": "06-10-2026",
  "unloadDate": "07-10-2026",
  "shipper": {
    "name": "CERÁMICAS DEL MEDITERRÁNEO S.A.",
    "taxId": "A12345674",
    "country": "ES",
    "address": "Carretera de Alcora km 3",
    "postalCode": "12006",
    "city": "Castellón de la Plana"
  },
  "carrier": "self"
}

{
  "id": "cmuqr2x0k0001vo8k3d1f9a7b",
  "draftId": "cmuqr2x0k0001vo8k3d1f9a7b",
  "object": "api_draft",
  "origin": "api",
  "status": "open",
  "version": 1,
  "externalId": "VIAJE-4471",
  "data": {
    "...": "el cuerpo que enviaste"
  },
  "ready": false,
  "issues": [
    {
      "path": "/vehicle",
      "code": "invalid_type",
      "message": "Requerido"
    },
    {
      "path": "/shipments",
      "code": "invalid_type",
      "message": "Requerido"
    }
  ],
  "decaId": null,
  "generatedAt": null,
  "cancelledAt": null,
  "createdAt": "2026-10-02T11:12:04+02:00",
  "updatedAt": "2026-10-02T11:12:04+02:00",
  "links": {
    "self": "/api/v1/drafts/cmuqr2x0k0001vo8k3d1f9a7b",
    "generate": "/api/v1/drafts/cmuqr2x0k0001vo8k3d1f9a7b/generate"
  }
}

Para completarlo, envía solo lo que cambia con PATCH /api/v1/drafts/{id} (JSON Merge Patch: los objetos se combinan, las listas como shipments se sustituyen enteras y null borra un campo). Si quieres evitar sobrescribir un cambio hecho por otro proceso, envía la cabecera If-Match con el ETag que recibiste: si el borrador cambió entretanto, la respuesta es 412.

{
  "vehicle": {
    "tractorPlate": "1234 KLM"
  },
  "shipments": [
    {
      "loadLocation": {
        "name": "Planta 1",
        "address": "Carretera de Alcora km 3",
        "postalCode": "12006",
        "city": "Castellón de la Plana",
        "country": "ES"
      },
      "unloadLocation": {
        "name": "Almacenes Norte",
        "address": "Polígono Arasur, calle C 14",
        "postalCode": "01230",
        "city": "Ribabellosa",
        "country": "ES"
      },
      "goods": "Azulejo cerámico en palés",
      "weight": 18400
    }
  ]
}

Cuando ready sea true, genera el DeCA con POST /api/v1/drafts/{id}/generate. Pasa exactamente las mismas validaciones y el mismo límite de plan que POST /api/v1/decas y responde 201 con el DeCA vigente (PDF, QR y URL de verificación). El borrador queda generated con su decaId y la fecha de generación; ya no se puede modificar, y repetir la llamada devuelve el mismo DeCA (200), nunca uno nuevo. El resto de borradores no cambia. GET /api/v1/drafts lista los abiertos (?status=generated, cancelled o all para el resto) y DELETE /api/v1/drafts/{id} descarta uno que ya no necesites.

Cada borrador pertenece a tu empresa y a la integración que lo creó: con otra clave, un draftId ajeno responde 404, igual que uno que no existe. Esta función es nueva y no cambia nada de lo anterior: POST /api/v1/decas con draft: true o completionRequest sigue funcionando igual.

Ejemplo completo: una operación real de transporte

Así encaja todo en un día normal: tu ERP o TMS prepara el transporte, tu equipo lo revisa en el panel si hace falta, el transportista completa las matrículas y tu sistema recibe cada paso por webhook. Cada paso es una llamada de esta página.

1. 1. Sincroniza tus datos habituales desde el ERP

   PUT /api/v1/saved/companies/CLI-0042 · PUT /api/v1/saved/places/ALM-VLC

   Con tu identificador estable (externalId): repetir la llamada actualiza, nunca duplica. Lo que cambies en el panel se ve en la API y al revés.

2. 2. Crea el borrador del transporte

   POST /api/v1/drafts (Idempotency-Key)

   Con lo que el ERP ya sabe (cargador, lugares, mercancía, fechas). Puede faltar la matrícula: responde ready=false e issues con lo pendiente. No consume cupo.

3. 3. Continúalo desde el panel si hace falta

   Mis DeCA › Borradores pendientes

   El borrador aparece con la etiqueta «API» y tu externalId. Con deca:read_company tu integración ve también los borradores iniciados en la web, incluidos los programados.

4. 4. Pide las matrículas al transportista

   POST /api/v1/decas/{id}/completion-request

   Un enlace temporal para que el transportista complete solo los campos pedidos. Cuando los completa recibes completion.completed (solo los nombres de los campos, nunca los valores).

5. 5. Genera el DeCA y su orden de carga

   POST /api/v1/decas con loadOrder { format: "separate", price, conditions }

   Un DeCA con su QR y su PDF, y la orden vinculada (junta o separada) si tu empresa es el cargador. Recibes deca.created y load_order.issued. Repetir con la misma Idempotency-Key no crea nada nuevo.

6. 6. Recibe las confirmaciones por webhook

   deca.created · load_order.issued · load_order.accepted · deca.corrected · deca.service_finished

   Verifica la firma DeCA-Signature y descarta duplicados por id de evento. load_order.accepted llega cuando el transportista acepta la orden por su enlace.

7. 7. Recupera referencias y documentos

   GET /api/v1/decas/{id} · GET /api/v1/decas/{id}/pdf · GET /api/v1/load-orders?decaId={id}

   La referencia DECA-…, la URL de verificación, el PDF vigente, la orden con su estado y aceptación, y service.finished cuando se marca el servicio como finalizado.

Entorno de pruebas (sandbox)

Crea en Integraciones → Centro de integración una clave de pruebas: empieza por fvd_test_. Con ella tu integración llama a las mismas URL con los mismos cuerpos y recibe las mismas validaciones y errores, pero los documentos son de prueba: no son DeCA, no consumen tu cupo, no aparecen en el Historial ni en la facturación y su PDF lleva la marca «PRUEBA · SIN VALIDEZ». Cuando todo funcione, cambia la clave por una real (fvd_live_) sin tocar nada más.

• Funcionan con la clave de pruebas: GET /me (responde mode: "test"), POST /decas/validate, POST /decas, GET /decas, GET /decas/{id}, /status, /pdf, /corrections y /annulment. El resto responde 403 sandbox_not_supported.
• Las respuestas llevan livemode: false, el id empieza por test_ y la referencia por PRUEBA-.
• Los webhooks de tus documentos de prueba se envían a tus endpoints con livemode: false: así pruebas también la recepción.
• Hasta 2 claves de pruebas activas, aparte de las 2 reales.

Errores a demanda. Crea un documento con externalId: "PRUEBA-ERROR-<código>" y la API responderá ese error, igual que en real, para que compruebes cómo lo trata tu programa:

Webhooks: tu sistema se entera solo

Configura en Integraciones → Centro de integración → Webhooks la URL https:// de tu sistema y los eventos que te interesan. Cada aviso es un POST JSON firmado; tu servidor debe responder 2xx en menos de 10 segundos. Si no, reintentamos a los 1, 5 y 30 minutos y a las 2, 6, 12 y 24 horas, siempre con el mismo DeCA-Event-Id, para que puedas descartar duplicados. Desde el panel puedes enviar un evento de prueba, ver cada entrega y reenviar las fallidas.

Cabeceras: DeCA-Event-Id, DeCA-Event-Type y DeCA-Signature con el formato t=<segundos>,v1=<HMAC-SHA256 hex de "<t>.<cuerpo>">, calculado con el secreto que se muestra una sola vez al crear el endpoint. Los avisos incluyen identificadores y referencias, no los datos personales del DeCA: consúltalos con la API si los necesitas.

{
  "id": "evt_4n8Qx2kY0pLmRs7T",
  "type": "deca.created",
  "createdAt": "2026-10-08T10:41:00+02:00",
  "livemode": true,
  "data": {
    "deca": {
      "id": "cmupjfyhp00v8vos059cdhihy",
      "reference": "DECA-A4F2C9E1",
      "externalId": "TR-45882",
      "status": "active",
      "version": 1,
      "verificationUrl": "https://decaprofesional.es/d/A4F2C9E1…",
      "links": {
        "self": "/api/v1/decas/cmupjfyhp00v8vos059cdhihy",
        "pdf": "/api/v1/decas/cmupjfyhp00v8vos059cdhihy/pdf"
      }
    },
    "source": "api"
  }
}

import { createHmac, timingSafeEqual } from "node:crypto";

// rawBody: el cuerpo EXACTO recibido (sin volver a serializarlo); secret: dcwh_… (Integraciones → Webhooks)
export function webhookValido(rawBody, signatureHeader, secret) {
  const m = /^t=(\d+),v1=([a-f0-9]{64})$/.exec(signatureHeader ?? "");
  if (!m) return false;
  if (Math.abs(Date.now() / 1000 - Number(m[1])) > 300) return false; // más de 5 min: posible reenvío malicioso
  const esperado = createHmac("sha256", secret).update(`${m[1]}.${rawBody}`).digest();
  const recibido = Buffer.from(m[2], "hex");
  return esperado.length === recibido.length && timingSafeEqual(esperado, recibido);
}
// Responde 2xx en menos de 10 s y procesa después. Usa DeCA-Event-Id para no procesar dos veces el mismo evento.

Power Automate y Make: conectar sin escribir código

Si tu ERP o TMS ya se conecta con Power Automate o con Make (Odoo, Sage, Holded, Dynamics y muchos más lo hacen), puedes generar DeCA sin escribir código: la herramienta lee la expedición de tu sistema y llama a la API. Lo que no podemos hacer por ti es que tu programa exporte sus datos: eso depende de que tenga integración con estas herramientas o una API propia. No son integraciones nativas: te damos la definición para crear un conector personalizado y una guía paso a paso.

Tabla de equivalencias: de tu ERP a la API

El concepto es el mismo en cualquier ERP; la columna de Odoo indica el campo estándar de sus módulos Inventario, Contactos y Flota. En Sage, Holded o Dynamics busca el campo equivalente: el nombre exacto depende de cada instalación.