DeCA API documentation

Completion of a DeCA by a third party

If your ERP is missing data that another company knows — for example, the registration plate the carrier will assign or the exact unloading town — you can still create the DeCA and request that data from a third party. It is the same “Completion by the counterparty” feature as on the website: the third party receives an email with a secure link, fills in only the fields you ask for and, once no mandatory data is missing, the DeCA is generated automatically and becomes active, with its PDF, its QR code and its verification URL. It requires the same access as the rest of the API (Business plan with the API add-on active).

Add completionRequest to the body of POST /api/v1/decas, with the recipient's email (recipientEmail) and the fields they must complete (fields). Those fields may arrive empty; all the others must be valid, just as in a normal creation. The response is 202 Accepted with a draft (object: "deca_draft"), not an active DeCA. Optionally: recipientName, recipientType (shipper | carrier | authorized_person) and expiresInHours (1–48; 24 by default).

As on the website, only the registration plates and the unloading details can be requested: the loading place, the province, the country, the parties, the goods and the weight are always provided by whoever creates the DeCA (otherwise the API returns 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": []
}

The secure link

The link is sent by email to the recipient only; the API never returns it. It is personal, single-use and expires after expiresInHours hours. The third party needs no account, sees only your company name and the fields you ask for, and cannot change any other data. The email states which company is requesting the data, the expiry date and what happens when the data is submitted.

When the third party completes the data

The data is validated and added to the draft. If no mandatory data is missing any more, the DeCA is generated automatically with your integration as its author (it keeps your externalId), the draft becomes issued and its decaId is the active DeCA; the third party receives a copy by email. If data is still missing, the draft stays in draft and missingFields tells you which.

Checking the status

GET /api/v1/decas/{id} responds to both the draft id and the id of the issued DeCA (which also includes completionRequest). Draft statuses:

• pending_completion — A request is open: the third party has not sent the data yet.
• draft — Data is missing (missingFields) and no request is open: ask for the data or resend.
• ready — Nothing is missing, but the DeCA could not be issued (for example, the plan allowance is used up). It can be issued from the dashboard.
• issued — The DeCA is now in force: retrieve it with decaId.
• cancelled — The draft was cancelled from the dashboard.

completionRequest.status: pending, completed, expired or replaced (superseded by a resend).

{
  "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
  }
}

Requesting the data later

You can also create the draft first ("draft": true instead of completionRequest) and request the data later. If a request is already pending, the response is 409 completion_request_pending; if the DeCA is already active, 409 deca_already_issued (use a correction).

{
  "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
  }
}

Resending the request

POST /api/v1/decas/{id}/completion-request/resend sends a new link to the same recipient with the fields that have not been completed yet; the previous link stops working. Use it, for example, when the link has expired. Optional body: { "expiresInHours": 24 }. Up to 5 resends per draft per hour; a request that has already been completed returns 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
  }
}

Security and idempotency

A credential only sees and manages the drafts of its own integration (with deca:read_company, it can read all of its company's drafts). All these calls require Idempotency-Key: if you repeat one with the same key, you receive the same response (200, Idempotent-Replayed: true) without creating another draft, another request or another email. Every step is logged: who requested it, when the link was opened, who completed what and when the DeCA was generated.

Drafts: several transports at once

If your system prepares several transports in parallel, open one draft for each with POST /api/v1/drafts. Each draft is independent and has its own draftId: you can have as many open at the same time as you need, complete them step by step and generate each DeCA when it is ready, without one draft overwriting another. A draft does not use your plan allowance; the allowance is used only when the final DeCA is generated.

The body is the same as for POST /api/v1/decas, but it may be incomplete. Each response states ready and, if something is missing, issues with the same error details that direct creation would return.

Open drafts also appear on the website, under My DeCA › Pending drafts (with the “API” label and your externalId), for the users of your company who can create DeCAs. From there they can be continued in the wizard, generated or discarded. If it is generated from the website, the draft becomes generated with its decaId (and an empty generatedByApiCredentialId); if it is discarded, it becomes cancelled. Check it with 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": {
    "...": "the body you sent"
  },
  "ready": false,
  "issues": [
    {
      "path": "/vehicle",
      "code": "invalid_type",
      "message": "Required"
    },
    {
      "path": "/shipments",
      "code": "invalid_type",
      "message": "Required"
    }
  ],
  "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"
  }
}

To complete it, send only what changes with PATCH /api/v1/drafts/{id} (JSON Merge Patch: objects are merged, arrays such as shipments are replaced in full and null deletes a field). To avoid overwriting a change made by another process, send the If-Match header with the ETag you received: if the draft has changed in the meantime, the response is 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
    }
  ]
}

When ready is true, generate the DeCA with POST /api/v1/drafts/{id}/generate. It goes through exactly the same validations and the same plan limit as POST /api/v1/decas and returns 201 with the active DeCA (PDF, QR code and verification URL). The draft becomes generated with its decaId and the generation date; it can no longer be modified, and repeating the call returns the same DeCA (200), never a new one. The other drafts are unaffected. GET /api/v1/drafts lists the open ones (?status=generated, cancelled or all for the rest) and DELETE /api/v1/drafts/{id} discards one you no longer need.

Each draft belongs to your company and to the integration that created it: with another key, someone else's draftId returns 404, just like one that does not exist. This feature is new and changes nothing that existed before: POST /api/v1/decas with draft: true or completionRequest keeps working as it did.

End-to-end example: a real transport operation

This is how everything fits together on a normal day: your ERP or TMS prepares the transport, your team reviews it in the dashboard if needed, the carrier completes the registration plates and your system receives each step by webhook. Each step is a call described on this page.

1. 1. Sync your saved data from the ERP

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

   With your stable identifier (externalId): repeating the call updates, it never duplicates. Whatever you change in the dashboard is visible in the API and vice versa.

2. 2. Create the transport draft

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

   With what the ERP already knows (shipper, places, goods, dates). The registration plate may be missing: it returns ready=false and issues listing what is pending. It does not use up the allowance.

3. 3. Continue it from the dashboard if needed

   Mis DeCA › Borradores pendientes

   The draft appears with the «API» label and your externalId. With deca:read_company your integration also sees the drafts started on the website, including scheduled ones.

4. 4. Ask the carrier for the registration plates

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

   A temporary link so the carrier completes only the requested fields. When they complete them you receive completion.completed (only the field names, never the values).

5. 5. Generate the DeCA and its load order

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

   A DeCA with its QR code and PDF, and the linked load order (combined or separate) if your company is the shipper. You receive deca.created and load_order.issued. Repeating with the same Idempotency-Key creates nothing new.

6. 6. Receive the confirmations by webhook

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

   Verify the DeCA-Signature signature and discard duplicates by event id. load_order.accepted arrives when the carrier accepts the order through their link.

7. 7. Retrieve references and documents

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

   The DECA-… reference, the verification URL, the current PDF, the load order with its status and acceptance, and service.finished when the service is marked as finished.

Test environment (sandbox)

In Integrations → Integration hub, create a test key: it starts with fvd_test_. With it your integration calls the same URLs with the same bodies and receives the same validations and errors, but the documents are test documents: they are not DeCAs, they do not use your allowance, they do not appear in the History or in billing, and their PDF carries the watermark “PRUEBA · SIN VALIDEZ” (test · not valid). When everything works, swap the key for a live one (fvd_live_) without changing anything else.

• Available with the test key: GET /me (returns mode: "test"), POST /decas/validate, POST /decas, GET /decas, GET /decas/{id}, /status, /pdf, /corrections and /annulment. Everything else returns 403 sandbox_not_supported.
• Responses carry livemode: false, the id starts with test_ and the reference with PRUEBA-.
• Webhooks for your test documents are sent to your endpoints with livemode: false, so you can test receiving them as well.
• Up to 2 active test keys, in addition to the 2 live ones.

Errors on demand. Create a document with externalId: "PRUEBA-ERROR-<code>" and the API will return that error, exactly as in production, so you can check how your software handles it:

Webhooks: your system finds out on its own

In Integrations → Integration hub → Webhooks, set the https:// URL of your system and the events you are interested in. Each notification is a signed JSON POST; your server must respond with 2xx within 10 seconds. Otherwise we retry after 1, 5 and 30 minutes and after 2, 6, 12 and 24 hours, always with the same DeCA-Event-Id, so that you can discard duplicates. From the dashboard you can send a test event, view each delivery and resend the failed ones.

Headers: DeCA-Event-Id, DeCA-Event-Type and DeCA-Signature in the format t=<seconds>,v1=<HMAC-SHA256 hex of "<t>.<body>">, computed with the secret that is shown only once, when the endpoint is created. Notifications include identifiers and references, not the personal data in the DeCA: retrieve it through the API if you need it.

{
  "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: the EXACT body received (do not re-serialise it); secret: dcwh_… (Integrations → Webhooks)
export function isValidWebhook(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; // older than 5 min: possible replay attack
  const expected = createHmac("sha256", secret).update(`${m[1]}.${rawBody}`).digest();
  const received = Buffer.from(m[2], "hex");
  return expected.length === received.length && timingSafeEqual(expected, received);
}
// Respond 2xx within 10 s and process afterwards. Use DeCA-Event-Id so you never process the same event twice.

Power Automate and Make: connect without writing code

If your ERP or TMS already connects to Power Automate or Make (Odoo, Sage, Holded, Dynamics and many more do), you can generate DeCAs without writing code: the tool reads the shipment from your system and calls the API. What we cannot do for you is make your software export its data: that depends on it having an integration with these tools or an API of its own. These are not native integrations: we provide the definition for building a custom connector and a step-by-step guide.

Field mapping: from your ERP to the API

The concept is the same in any ERP; the Odoo column shows the standard field of its Inventory, Contacts and Fleet modules. In Sage, Holded or Dynamics, look for the equivalent field: the exact name depends on each installation.