{"openapi":"3.1.0","info":{"title":"DeCA Profesional API","version":"1","description":"REST API to create, read, correct and annul DeCA from an ERP or TMS. API Advanced: Business plan + API Advanced add-on (€49.95/month + VAT). API Lite (Professional) supports only the basic routes: see /developers/openapi-lite.json.\n\nAuthentication: header `Authorization: Bearer <key>`. Keys are shown only once; never use them in a browser.\n\nDates in DD-MM-YYYY and times in Europe/Madrid time (ISO 8601 with its offset, e.g. 2026-10-08T10:41:00+02:00).\n\nLimits: 60 requests/minute per key, maximum body 256 KB, up to 50 shipments per DeCA.\n\nErrors: `error.code` is stable — branch your integration on it, never on the text. `error.message` is informative: Spanish by default, English when the request sends `Accept-Language: en`.\n\nKey scopes:\n- `deca:create`: Create DeCAs (POST /decas, also in batches) and validate them (POST /decas/validate), create, modify and generate drafts, and ask a third party for data.\n- `deca:read`: Read and list the DeCAs created by this integration, and its drafts, batches and load orders.\n- `deca:read_company`: Extend read access to all the company's DeCAs. It never extends write access.\n- `deca:correct`: Correct DeCAs created by this integration, record vehicle changes, and mark a service as finished or reopen it.\n- `deca:annul`: Annul DeCAs created by this integration.\n- `saved:read`: Read the company's saved data: saved companies, vehicles, places and shipments.\n- `saved:write`: Create, update (PUT by externalId) and delete saved data from your ERP or TMS."},"servers":[{"url":"https://decaprofesional.es"}],"webhooks":{"deca.created":{"post":{"summary":"deca.created","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"}}}},"responses":{"200":{"description":"Answer 2xx within 10 s; otherwise the delivery is retried for 24 h."}}}},"deca.corrected":{"post":{"summary":"deca.corrected","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"}}}},"responses":{"200":{"description":"Answer 2xx within 10 s; otherwise the delivery is retried for 24 h."}}}},"deca.annulled":{"post":{"summary":"deca.annulled","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"}}}},"responses":{"200":{"description":"Answer 2xx within 10 s; otherwise the delivery is retried for 24 h."}}}},"draft.generated":{"post":{"summary":"draft.generated","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"}}}},"responses":{"200":{"description":"Answer 2xx within 10 s; otherwise the delivery is retried for 24 h."}}}},"completion.completed":{"post":{"summary":"completion.completed","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"}}}},"responses":{"200":{"description":"Answer 2xx within 10 s; otherwise the delivery is retried for 24 h."}}}},"deca.service_finished":{"post":{"summary":"deca.service_finished","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"}}}},"responses":{"200":{"description":"Answer 2xx within 10 s; otherwise the delivery is retried for 24 h."}}}},"deca.service_reopened":{"post":{"summary":"deca.service_reopened","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"}}}},"responses":{"200":{"description":"Answer 2xx within 10 s; otherwise the delivery is retried for 24 h."}}}},"load_order.issued":{"post":{"summary":"load_order.issued","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"}}}},"responses":{"200":{"description":"Answer 2xx within 10 s; otherwise the delivery is retried for 24 h."}}}},"load_order.accepted":{"post":{"summary":"load_order.accepted","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"}}}},"responses":{"200":{"description":"Answer 2xx within 10 s; otherwise the delivery is retried for 24 h."}}}}},"security":[{"bearerAuth":[]}],"paths":{"/api/v1/me":{"get":{"summary":"Checks the credential: integration, company, permissions, limits and usage this month.","description":"The first endpoint to call to verify the connection.\n\nNo specific scope required.","parameters":[],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Me"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/decas/validate":{"post":{"summary":"Validates a DeCA without creating it: same rules as creation.","description":"It creates no DeCA, generates no PDF and does not use up the plan allowance.\n\nRequired scope: deca:create.","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DecaCreate"},"example":{"externalId":"TR-45882","reference":"Pedido 88231","loadDate":"06-10-2026","unloadDate":"07-10-2026","vehicle":{"tractorPlate":"1234 KLM","trailerPlate":"R-5678-BBC"},"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","province":"Castellón","country":"ES"},"unloadLocation":{"name":"Entrepôt Lyon Sud","address":"12 Rue du Port","postalCode":"69007","city":"Lyon","country":"FR"},"goods":"Azulejo cerámico en palés","weight":18400,"recipient":"Céramique Rhône SARL"}]}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Validation"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/decas":{"post":{"summary":"Creates a DeCA and returns the verification URL, the reference and the PDF.","description":"Returns 201 (or 200 if it is a retry with the same Idempotency-Key). With completionRequest (or draft: true) it creates a draft and returns 202: see «Completion of a DeCA by a third party».\n\nRequired scope: deca:create.","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"Unique key per operation (8–255 characters). A retry with the same key and the same body returns the same result."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DecaCreate"},"example":{"externalId":"TR-45882","reference":"Pedido 88231","loadDate":"06-10-2026","unloadDate":"07-10-2026","vehicle":{"tractorPlate":"1234 KLM","trailerPlate":"R-5678-BBC"},"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","province":"Castellón","country":"ES"},"unloadLocation":{"name":"Entrepôt Lyon Sud","address":"12 Rue du Port","postalCode":"69007","city":"Lyon","country":"FR"},"goods":"Azulejo cerámico en palés","weight":18400,"recipient":"Céramique Rhône SARL"}]}}}},"responses":{"200":{"description":"Retry with the same Idempotency-Key and the same body: the original result (header Idempotent-Replayed: true).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Deca"},"example":{"id":"cmg4x2k9a0001l508h3n7q2rz","reference":"DECA-Q3VJ9KXA","externalId":"TR-45882","groupageRef":null,"status":"active","availability":"public","version":1,"createdAt":"2026-10-05T09:41:12+02:00","updatedAt":"2026-10-05T09:41:12+02:00","annulledAt":null,"service":{"finished":false,"finishedAt":null,"note":null},"serviceType":"goods","servicePeriod":{"start":"06-10-2026","end":"07-10-2026","publicUntil":"14-10-2026"},"verification":{"url":"https://decaprofesional.es/d/q3vj9kxa7Rm2…","note":"La URL cambia con cada corrección: imprime o envía siempre la última."},"pdf":{"href":"/api/v1/decas/cmg4x2k9a0001l508h3n7q2rz/pdf","sha256":"9f2c4e…","contentType":"application/pdf"},"data":{"reference":"Pedido 88231","notes":null,"loadDate":"06-10-2026","unloadDate":"07-10-2026","vehicle":{"tractorPlate":"1234KLM","trailerPlate":"R5678BBC"},"currentVehicle":{"tractorPlate":"1234KLM","trailerPlate":"R5678BBC"},"vehicleChanges":[],"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":{"name":"TRANSPORTES EJEMPLO S.L.","taxId":"B12345674","country":null,"address":"Polígono Industrial 5","postalCode":"46540","city":"El Puig"},"shipments":[{"loadLocation":{"name":"Planta 1","address":"Carretera de Alcora km 3","postalCode":"12006","city":"Castellón de la Plana","province":"Castellón","country":"ES","countryName":"España"},"unloadLocation":{"name":"Entrepôt Lyon Sud","address":"12 Rue du Port","postalCode":"69007","city":"Lyon","province":null,"country":"FR","countryName":"Francia"},"goods":"Azulejo cerámico en palés","weight":"18.400 kg","recipient":"Céramique Rhône SARL","loadDate":"06-10-2026","unloadDate":"07-10-2026"}],"totalWeight":"18.400 kg"},"warnings":[],"links":{"self":"/api/v1/decas/cmg4x2k9a0001l508h3n7q2rz","status":"/api/v1/decas/cmg4x2k9a0001l508h3n7q2rz/status","versions":"/api/v1/decas/cmg4x2k9a0001l508h3n7q2rz/versions","pdf":"/api/v1/decas/cmg4x2k9a0001l508h3n7q2rz/pdf"}}}}},"201":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Deca"},"example":{"id":"cmg4x2k9a0001l508h3n7q2rz","reference":"DECA-Q3VJ9KXA","externalId":"TR-45882","groupageRef":null,"status":"active","availability":"public","version":1,"createdAt":"2026-10-05T09:41:12+02:00","updatedAt":"2026-10-05T09:41:12+02:00","annulledAt":null,"service":{"finished":false,"finishedAt":null,"note":null},"serviceType":"goods","servicePeriod":{"start":"06-10-2026","end":"07-10-2026","publicUntil":"14-10-2026"},"verification":{"url":"https://decaprofesional.es/d/q3vj9kxa7Rm2…","note":"La URL cambia con cada corrección: imprime o envía siempre la última."},"pdf":{"href":"/api/v1/decas/cmg4x2k9a0001l508h3n7q2rz/pdf","sha256":"9f2c4e…","contentType":"application/pdf"},"data":{"reference":"Pedido 88231","notes":null,"loadDate":"06-10-2026","unloadDate":"07-10-2026","vehicle":{"tractorPlate":"1234KLM","trailerPlate":"R5678BBC"},"currentVehicle":{"tractorPlate":"1234KLM","trailerPlate":"R5678BBC"},"vehicleChanges":[],"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":{"name":"TRANSPORTES EJEMPLO S.L.","taxId":"B12345674","country":null,"address":"Polígono Industrial 5","postalCode":"46540","city":"El Puig"},"shipments":[{"loadLocation":{"name":"Planta 1","address":"Carretera de Alcora km 3","postalCode":"12006","city":"Castellón de la Plana","province":"Castellón","country":"ES","countryName":"España"},"unloadLocation":{"name":"Entrepôt Lyon Sud","address":"12 Rue du Port","postalCode":"69007","city":"Lyon","province":null,"country":"FR","countryName":"Francia"},"goods":"Azulejo cerámico en palés","weight":"18.400 kg","recipient":"Céramique Rhône SARL","loadDate":"06-10-2026","unloadDate":"07-10-2026"}],"totalWeight":"18.400 kg"},"warnings":[],"links":{"self":"/api/v1/decas/cmg4x2k9a0001l508h3n7q2rz","status":"/api/v1/decas/cmg4x2k9a0001l508h3n7q2rz/status","versions":"/api/v1/decas/cmg4x2k9a0001l508h3n7q2rz/versions","pdf":"/api/v1/decas/cmg4x2k9a0001l508h3n7q2rz/pdf"}}}}},"202":{"description":"With completionRequest or draft: true: draft created (and, where applicable, third-party completion request sent).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompletionRequestResult"}}}},"default":{"$ref":"#/components/responses/Error"}}},"get":{"summary":"Lists the DeCAs, newest first, with cursor pagination.","description":"Filters: limit (1–100, default 25), cursor, externalId, groupageRef (groupage reference, G-…), status (active | annulled), createdFrom, createdTo (DD-MM-YYYY, days in Madrid time; createdTo includes the whole of that day). All API dates are in DD-MM-YYYY and all times in Madrid time.\n\nRequired scope: deca:read.","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Items per page (1–100, default 25)."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"nextCursor from the previous page."},{"name":"externalId","in":"query","required":false,"schema":{"type":"string"},"description":"Exact match on externalId."},{"name":"groupageRef","in":"query","required":false,"schema":{"type":"string"},"description":"Groupage reference (G-…); case-insensitive."},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["active","annulled"]},"description":"Administrative status."},{"name":"createdFrom","in":"query","required":false,"schema":{"type":"string","examples":["06-10-2026"]},"description":"Created on or after this day (DD-MM-YYYY, day in Europe/Madrid time; an ISO 8601 date-time with time zone is also accepted)."},{"name":"createdTo","in":"query","required":false,"schema":{"type":"string","examples":["06-10-2026"]},"description":"Created up to and including this day (DD-MM-YYYY, day in Europe/Madrid time; an ISO 8601 date-time with time zone is also accepted)."}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DecaList"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/decas/{id}":{"get":{"summary":"The full DeCA: status, service period, verification URL, PDF and data.","description":"Required scope: deca:read.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"DeCA identifier."}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Deca"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/decas/{id}/status":{"get":{"summary":"Lightweight status (version, availability, verification URL) for periodic polling.","description":"Required scope: deca:read.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"DeCA identifier."}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DecaStatus"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/decas/{id}/versions":{"get":{"summary":"Version history: reason for the change, origin (api / user), and the URL and PDF of each version.","description":"Required scope: deca:read.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"DeCA identifier."}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VersionList"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/decas/{id}/pdf":{"get":{"summary":"Downloads the PDF (current version or ?version=N).","description":"Headers X-Pdf-Sha256 (PDF fingerprint) and X-Deca-Status (active | annulled).\n\nRequired scope: deca:read.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"DeCA identifier."},{"name":"version","in":"query","required":false,"schema":{"type":"integer","minimum":1},"description":"Version number (default: the current version)."}],"responses":{"200":{"description":"Success.","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/decas/{id}/corrections":{"post":{"summary":"Corrects a DeCA: creates a new version with a new URL, QR code and PDF.","description":"Returns 201 with the new version (200 if it is a retry with the same Idempotency-Key). Only DeCAs created by the same integration; previous versions are kept.\n\nRequired scope: deca:correct.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"DeCA identifier."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"Unique key per operation (8–255 characters). A retry with the same key and the same body returns the same result."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Correction"},"example":{"changeReason":"Trailer registration plate changed","deca":{"externalId":"TR-45882","reference":"Pedido 88231","loadDate":"06-10-2026","unloadDate":"07-10-2026","vehicle":{"tractorPlate":"1234 KLM","trailerPlate":"R-9012-CCD"},"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","province":"Castellón","country":"ES"},"unloadLocation":{"name":"Entrepôt Lyon Sud","address":"12 Rue du Port","postalCode":"69007","city":"Lyon","country":"FR"},"goods":"Azulejo cerámico en palés","weight":18400,"recipient":"Céramique Rhône SARL"}]}}}}},"responses":{"200":{"description":"Retry with the same Idempotency-Key and the same body: the original result (header Idempotent-Replayed: true).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Deca"},"example":{"id":"cmg4x2k9a0001l508h3n7q2rz","reference":"DECA-Q3VJ9KXA","externalId":"TR-45882","groupageRef":null,"status":"active","availability":"public","version":1,"createdAt":"2026-10-05T09:41:12+02:00","updatedAt":"2026-10-05T09:41:12+02:00","annulledAt":null,"service":{"finished":false,"finishedAt":null,"note":null},"serviceType":"goods","servicePeriod":{"start":"06-10-2026","end":"07-10-2026","publicUntil":"14-10-2026"},"verification":{"url":"https://decaprofesional.es/d/q3vj9kxa7Rm2…","note":"La URL cambia con cada corrección: imprime o envía siempre la última."},"pdf":{"href":"/api/v1/decas/cmg4x2k9a0001l508h3n7q2rz/pdf","sha256":"9f2c4e…","contentType":"application/pdf"},"data":{"reference":"Pedido 88231","notes":null,"loadDate":"06-10-2026","unloadDate":"07-10-2026","vehicle":{"tractorPlate":"1234KLM","trailerPlate":"R5678BBC"},"currentVehicle":{"tractorPlate":"1234KLM","trailerPlate":"R5678BBC"},"vehicleChanges":[],"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":{"name":"TRANSPORTES EJEMPLO S.L.","taxId":"B12345674","country":null,"address":"Polígono Industrial 5","postalCode":"46540","city":"El Puig"},"shipments":[{"loadLocation":{"name":"Planta 1","address":"Carretera de Alcora km 3","postalCode":"12006","city":"Castellón de la Plana","province":"Castellón","country":"ES","countryName":"España"},"unloadLocation":{"name":"Entrepôt Lyon Sud","address":"12 Rue du Port","postalCode":"69007","city":"Lyon","province":null,"country":"FR","countryName":"Francia"},"goods":"Azulejo cerámico en palés","weight":"18.400 kg","recipient":"Céramique Rhône SARL","loadDate":"06-10-2026","unloadDate":"07-10-2026"}],"totalWeight":"18.400 kg"},"warnings":[],"links":{"self":"/api/v1/decas/cmg4x2k9a0001l508h3n7q2rz","status":"/api/v1/decas/cmg4x2k9a0001l508h3n7q2rz/status","versions":"/api/v1/decas/cmg4x2k9a0001l508h3n7q2rz/versions","pdf":"/api/v1/decas/cmg4x2k9a0001l508h3n7q2rz/pdf"}}}}},"201":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Deca"},"example":{"id":"cmg4x2k9a0001l508h3n7q2rz","reference":"DECA-Q3VJ9KXA","externalId":"TR-45882","groupageRef":null,"status":"active","availability":"public","version":1,"createdAt":"2026-10-05T09:41:12+02:00","updatedAt":"2026-10-05T09:41:12+02:00","annulledAt":null,"service":{"finished":false,"finishedAt":null,"note":null},"serviceType":"goods","servicePeriod":{"start":"06-10-2026","end":"07-10-2026","publicUntil":"14-10-2026"},"verification":{"url":"https://decaprofesional.es/d/q3vj9kxa7Rm2…","note":"La URL cambia con cada corrección: imprime o envía siempre la última."},"pdf":{"href":"/api/v1/decas/cmg4x2k9a0001l508h3n7q2rz/pdf","sha256":"9f2c4e…","contentType":"application/pdf"},"data":{"reference":"Pedido 88231","notes":null,"loadDate":"06-10-2026","unloadDate":"07-10-2026","vehicle":{"tractorPlate":"1234KLM","trailerPlate":"R5678BBC"},"currentVehicle":{"tractorPlate":"1234KLM","trailerPlate":"R5678BBC"},"vehicleChanges":[],"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":{"name":"TRANSPORTES EJEMPLO S.L.","taxId":"B12345674","country":null,"address":"Polígono Industrial 5","postalCode":"46540","city":"El Puig"},"shipments":[{"loadLocation":{"name":"Planta 1","address":"Carretera de Alcora km 3","postalCode":"12006","city":"Castellón de la Plana","province":"Castellón","country":"ES","countryName":"España"},"unloadLocation":{"name":"Entrepôt Lyon Sud","address":"12 Rue du Port","postalCode":"69007","city":"Lyon","province":null,"country":"FR","countryName":"Francia"},"goods":"Azulejo cerámico en palés","weight":"18.400 kg","recipient":"Céramique Rhône SARL","loadDate":"06-10-2026","unloadDate":"07-10-2026"}],"totalWeight":"18.400 kg"},"warnings":[],"links":{"self":"/api/v1/decas/cmg4x2k9a0001l508h3n7q2rz","status":"/api/v1/decas/cmg4x2k9a0001l508h3n7q2rz/status","versions":"/api/v1/decas/cmg4x2k9a0001l508h3n7q2rz/versions","pdf":"/api/v1/decas/cmg4x2k9a0001l508h3n7q2rz/pdf"}}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/decas/{id}/vehicles":{"get":{"summary":"Vehicles of the transport: the initial one and every recorded change, with the current one flagged.","description":"Required scope: deca:read.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"DeCA identifier."}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VehicleList"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/decas/{id}/vehicle-changes":{"post":{"summary":"Records a vehicle change (tractor unit and, if it changes, trailer) during the transport.","description":"It is a correction: a new version with a new URL, QR code and PDF, which does not use up any DeCA from the plan. The date (DD-MM-YYYY) must fall within the transport and after the previous change. Without trailerPlate the previous trailer is kept. Returns 201 (200 if it is a retry with the same Idempotency-Key).\n\nRequired scope: deca:correct.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"DeCA identifier."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"Unique key per operation (8–255 characters). A retry with the same key and the same body returns the same result."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VehicleChange"},"example":{"tractorPlate":"5678 NPR","effectiveAt":"07-10-2026","reason":"Tractor unit broke down en route"}}}},"responses":{"200":{"description":"Retry with the same Idempotency-Key and the same body: the original result (header Idempotent-Replayed: true).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Deca"}}}},"201":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Deca"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/decas/{id}/annulment":{"post":{"summary":"Annuls a DeCA. The annulment is final; repeating the call returns 200 with no changes.","description":"Only DeCAs created by the same integration.\n\nRequired scope: deca:annul.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"DeCA identifier."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Annulment"},"example":{"reason":"Order cancelled by the customer"}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Deca"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/decas/{id}/completion-request":{"post":{"summary":"Asks a third party, by email, for the data missing from a draft.","description":"Returns 201 (200 if it is a retry with the same Idempotency-Key). Only drafts of the same integration.\n\nRequired scope: deca:create.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"DeCA identifier."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"Unique key per operation (8–255 characters). A retry with the same key and the same body returns the same result."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompletionRequest"},"example":{"recipientEmail":"operaciones@transportista.example","fields":["vehicle.tractorPlate","shipments[0].unloadLocation.city"],"expiresInHours":48}}}},"responses":{"200":{"description":"Retry with the same Idempotency-Key and the same body: the original result (header Idempotent-Replayed: true).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompletionRequestResult"}}}},"201":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompletionRequestResult"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/decas/{id}/completion-request/resend":{"post":{"summary":"Resends the request with a new link (the previous one stops working).","description":"Returns 201 (200 if it is a retry). At most 5 resends per draft per hour.\n\nRequired scope: deca:create.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"DeCA identifier."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"Unique key per operation (8–255 characters). A retry with the same key and the same body returns the same result."}],"responses":{"200":{"description":"Retry with the same Idempotency-Key and the same body: the original result (header Idempotent-Replayed: true).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompletionRequestResult"}}}},"201":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompletionRequestResult"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/decas/batch":{"post":{"summary":"Creates up to 50 DeCAs in a single call (batch).","description":"Body { items: [ …same format as POST /decas… ] }. Returns 202 with the batch already validated: each item is pending or failed with its details (one error does not affect the others). Creation continues in the background; check GET /api/v1/batches/{id}. Each item uses up one DeCA from the plan, like a normal creation. The same Idempotency-Key with the same body returns the same batch (200); a DeCA is never duplicated.\n\nRequired scope: deca:create.","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"Unique key per operation (8–255 characters). A retry with the same key and the same body returns the same result."}],"responses":{"200":{"description":"Retry with the same Idempotency-Key and the same body: the original result (header Idempotent-Replayed: true).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Batch"}}}},"202":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Batch"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/batches/{id}":{"get":{"summary":"Status of the batch and result of each item (created, replayed, failed, pending).","description":"status changes from processing to completed when every item has finished.\n\nRequired scope: deca:read.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Batch identifier."}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Batch"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/batches/{id}/pdfs":{"get":{"summary":"Downloads a ZIP file with the current PDF of each DeCA created by the batch.","description":"Returns 409 batch_without_documents if the batch has not created any DeCA yet.\n\nRequired scope: deca:read.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Batch identifier."}],"responses":{"200":{"description":"Success.","content":{"application/zip":{"schema":{"type":"string","format":"binary"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/drafts":{"post":{"summary":"Opens a new, independent draft (partial data). It does not use up the allowance.","description":"Returns 201 with draftId (200 if it is a retry with the same Idempotency-Key).\n\nRequired scope: deca:create.","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"Unique key per operation (8–255 characters). A retry with the same key and the same body returns the same result."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DraftCreate"},"example":{"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"}}}},"responses":{"200":{"description":"Retry with the same Idempotency-Key and the same body: the original result (header Idempotent-Replayed: true).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Draft"}}}},"201":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Draft"}}}},"default":{"$ref":"#/components/responses/Error"}}},"get":{"summary":"Lists the drafts: status=open (default) | generated | cancelled | all.","description":"Paginated with limit and cursor, like /decas. Drafts belong to the company: with deca:read_company you also see the drafts started on the website (origin: \"web\") and those of other integrations, and you can complete, generate or discard them.\n\nRequired scope: deca:read.","parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["open","generated","cancelled","all"],"default":"open"},"description":"Draft status (default open)."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Items per page (1–100, default 25)."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"nextCursor from the previous page."}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DraftList"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/drafts/{id}":{"get":{"summary":"A draft, with ready and issues (what is still missing before it can be generated).","description":"Required scope: deca:read.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Draft identifier."}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Draft"}}}},"default":{"$ref":"#/components/responses/Error"}}},"patch":{"summary":"Modifies or completes an open draft (JSON Merge Patch).","description":"Optional If-Match with the ETag: 412 if another change arrived first.\n\nRequired scope: deca:create.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Draft identifier."},{"name":"If-Match","in":"header","required":false,"schema":{"type":"string"},"description":"ETag read from the draft: prevents overwriting someone else's changes (412 precondition_failed)."}],"requestBody":{"required":true,"content":{"application/merge-patch+json":{"schema":{"$ref":"#/components/schemas/DraftPatch"},"example":{"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}]}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Draft"}}}},"default":{"$ref":"#/components/responses/Error"}}},"delete":{"summary":"Discards an open draft (it becomes cancelled).","description":"Required scope: deca:create.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Draft identifier."},{"name":"If-Match","in":"header","required":false,"schema":{"type":"string"},"description":"ETag read from the draft: prevents overwriting someone else's changes (412 precondition_failed)."}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Draft"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/drafts/{id}/generate":{"post":{"summary":"Generates the final DeCA from that draft; the other drafts do not change.","description":"201 with the DeCA; repeating the call returns the same DeCA (200). This is where the allowance is used up.\n\nRequired scope: deca:create.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Draft identifier."},{"name":"If-Match","in":"header","required":false,"schema":{"type":"string"},"description":"ETag read from the draft: prevents overwriting someone else's changes (412 precondition_failed)."}],"responses":{"201":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Deca"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/decas/{id}/service-completion":{"post":{"summary":"Marks the service as finished (operational data; the DeCA, its PDF and its URL do not change).","description":"Optional body { note } (up to 500 characters). Idempotent: returns the DeCA with service.finished. 409 deca_annulled on an annulled DeCA. Webhook deca.service_finished.\n\nRequired scope: deca:correct.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"DeCA identifier."}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Deca"}}}},"default":{"$ref":"#/components/responses/Error"}}},"delete":{"summary":"Reopens a service marked as finished (it goes back to pending).","description":"Idempotent. Webhook deca.service_reopened.\n\nRequired scope: deca:correct.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"DeCA identifier."}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Deca"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/load-orders":{"get":{"summary":"Lists the load orders: number, status, format (combined or separate), linked DeCA, pending plates and acceptance.","description":"Filters: decaId, status (pending_vehicle | active | cancelled), limit (1–100). Without deca:read_company, only those of DeCAs created by your integration. It never includes the price or the conditions (they are in the PDF). To issue one: POST /api/v1/decas with loadOrder.\n\nRequired scope: deca:read.","parameters":[{"name":"decaId","in":"query","required":false,"schema":{"type":"string"},"description":"Only the load order of this DeCA."},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["pending_vehicle","active","cancelled"]},"description":"Load order status."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Maximum number of load orders (1–100, default 50)."}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoadOrderList"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/load-orders/{id}":{"get":{"summary":"A load order: status, current version, linked DeCA and acceptance by the carrier.","description":"Required scope: deca:read.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Load order identifier."}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoadOrder"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/load-orders/{id}/pdf":{"get":{"summary":"The PDF of the current version of the load order.","description":"Required scope: deca:read.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Load order identifier."}],"responses":{"200":{"description":"Success.","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/saved/companies":{"get":{"summary":"Lists the saved companies (shippers and carriers) of the company.","description":"In order of creation. Parameters: limit (1–100, default 50), cursor (nextCursor from the previous page) and externalId (exact match). Also includes the records created on the website (externalId null).\n\nRequired scope: saved:read.","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100},"description":"Items per page (default 50)."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"nextCursor from the previous page."},{"name":"externalId","in":"query","required":false,"schema":{"type":"string"},"description":"Exact match on externalId."}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavedList"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/saved/companies/{externalId}":{"get":{"summary":"Reads a record by the identifier from your ERP or TMS (externalId).","description":"Required scope: saved:read.","parameters":[{"name":"externalId","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9._~:-]{1,100}$"},"description":"The record's identifier in your ERP or TMS."}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavedRecord"}}}},"default":{"$ref":"#/components/responses/Error"}}},"put":{"summary":"Creates or updates the record with that externalId (sync without duplicates).","description":"Returns 201 when it creates the record and 200 when it updates it; repeating the same call leaves the same record. It is validated with the same rules as the website and appears immediately in Saved data («Datos habituales»). It never changes a DeCA that has already been generated.\n\nRequired scope: saved:write.","parameters":[{"name":"externalId","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9._~:-]{1,100}$"},"description":"The record's identifier in your ERP or TMS."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavedCompanyInput"},"example":{"name":"Cerámicas del Mediterráneo S.A.","taxId":"A12345674","address":"Carretera de Alcora km 3","postalCode":"12006","city":"Castellón de la Plana","role":"shipper"}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavedRecord"}}}},"201":{"description":"Created (no record with that externalId existed).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavedRecord"}}}},"default":{"$ref":"#/components/responses/Error"}}},"delete":{"summary":"Deletes the record with that externalId.","description":"It never changes a DeCA that has already been generated.\n\nRequired scope: saved:write.","parameters":[{"name":"externalId","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9._~:-]{1,100}$"},"description":"The record's identifier in your ERP or TMS."}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavedDeleted"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/saved/vehicles":{"get":{"summary":"Lists the saved vehicles (with their usual driver) of the company.","description":"In order of creation. Parameters: limit (1–100, default 50), cursor (nextCursor from the previous page) and externalId (exact match). Also includes the records created on the website (externalId null).\n\nRequired scope: saved:read.","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100},"description":"Items per page (default 50)."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"nextCursor from the previous page."},{"name":"externalId","in":"query","required":false,"schema":{"type":"string"},"description":"Exact match on externalId."}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavedList"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/saved/vehicles/{externalId}":{"get":{"summary":"Reads a record by the identifier from your ERP or TMS (externalId).","description":"Required scope: saved:read.","parameters":[{"name":"externalId","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9._~:-]{1,100}$"},"description":"The record's identifier in your ERP or TMS."}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavedRecord"}}}},"default":{"$ref":"#/components/responses/Error"}}},"put":{"summary":"Creates or updates the record with that externalId (sync without duplicates).","description":"Returns 201 when it creates the record and 200 when it updates it; repeating the same call leaves the same record. It is validated with the same rules as the website and appears immediately in Saved data («Datos habituales»). It never changes a DeCA that has already been generated.\n\nRequired scope: saved:write.","parameters":[{"name":"externalId","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9._~:-]{1,100}$"},"description":"The record's identifier in your ERP or TMS."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavedVehicleInput"},"example":{"tractorPlate":"1234 KLM","trailerPlate":"R-5678-BCD","alias":"Camión 12","habitualDriver":{"name":"Luis Pérez","phone":"+34 600 111 222","email":"luis@transportes.example"}}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavedRecord"}}}},"201":{"description":"Created (no record with that externalId existed).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavedRecord"}}}},"default":{"$ref":"#/components/responses/Error"}}},"delete":{"summary":"Deletes the record with that externalId.","description":"It never changes a DeCA that has already been generated.\n\nRequired scope: saved:write.","parameters":[{"name":"externalId","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9._~:-]{1,100}$"},"description":"The record's identifier in your ERP or TMS."}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavedDeleted"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/saved/places":{"get":{"summary":"Lists the saved loading and unloading places of the company.","description":"In order of creation. Parameters: limit (1–100, default 50), cursor (nextCursor from the previous page) and externalId (exact match). Also includes the records created on the website (externalId null).\n\nRequired scope: saved:read.","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100},"description":"Items per page (default 50)."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"nextCursor from the previous page."},{"name":"externalId","in":"query","required":false,"schema":{"type":"string"},"description":"Exact match on externalId."}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavedList"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/saved/places/{externalId}":{"get":{"summary":"Reads a record by the identifier from your ERP or TMS (externalId).","description":"Required scope: saved:read.","parameters":[{"name":"externalId","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9._~:-]{1,100}$"},"description":"The record's identifier in your ERP or TMS."}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavedRecord"}}}},"default":{"$ref":"#/components/responses/Error"}}},"put":{"summary":"Creates or updates the record with that externalId (sync without duplicates).","description":"Returns 201 when it creates the record and 200 when it updates it; repeating the same call leaves the same record. It is validated with the same rules as the website and appears immediately in Saved data («Datos habituales»). It never changes a DeCA that has already been generated.\n\nRequired scope: saved:write.","parameters":[{"name":"externalId","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9._~:-]{1,100}$"},"description":"The record's identifier in your ERP or TMS."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavedPlaceInput"},"example":{"name":"Almacén Norte","address":"Polígono Arasur, calle C 14","postalCode":"01230","city":"Ribabellosa","province":"Álava","type":"unload"}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavedRecord"}}}},"201":{"description":"Created (no record with that externalId existed).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavedRecord"}}}},"default":{"$ref":"#/components/responses/Error"}}},"delete":{"summary":"Deletes the record with that externalId.","description":"Returns 409 saved_in_use if a saved shipment uses that place.\n\nRequired scope: saved:write.","parameters":[{"name":"externalId","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9._~:-]{1,100}$"},"description":"The record's identifier in your ERP or TMS."}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavedDeleted"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/saved/shipments":{"get":{"summary":"Lists the saved shipments (loading place + unloading place + goods) of the company.","description":"In order of creation. Parameters: limit (1–100, default 50), cursor (nextCursor from the previous page) and externalId (exact match). Also includes the records created on the website (externalId null).\n\nRequired scope: saved:read.","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100},"description":"Items per page (default 50)."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"nextCursor from the previous page."},{"name":"externalId","in":"query","required":false,"schema":{"type":"string"},"description":"Exact match on externalId."}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavedList"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/saved/shipments/{externalId}":{"get":{"summary":"Reads a record by the identifier from your ERP or TMS (externalId).","description":"Required scope: saved:read.","parameters":[{"name":"externalId","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9._~:-]{1,100}$"},"description":"The record's identifier in your ERP or TMS."}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavedRecord"}}}},"default":{"$ref":"#/components/responses/Error"}}},"put":{"summary":"Creates or updates the record with that externalId (sync without duplicates).","description":"Returns 201 when it creates the record and 200 when it updates it; repeating the same call leaves the same record. It is validated with the same rules as the website and appears immediately in Saved data («Datos habituales»). Places are referenced by their externalId (loadPlaceExternalId, unloadPlaceExternalId): sync them first. It never changes a DeCA that has already been generated.\n\nRequired scope: saved:write.","parameters":[{"name":"externalId","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9._~:-]{1,100}$"},"description":"The record's identifier in your ERP or TMS."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavedShipmentInput"},"example":{"name":"Castellón → Arasur","loadPlaceExternalId":"ALM-CS","unloadPlaceExternalId":"ALM-NORTE","goods":"Azulejo cerámico en palés","weight":"18.400 kg"}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavedRecord"}}}},"201":{"description":"Created (no record with that externalId existed).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavedRecord"}}}},"default":{"$ref":"#/components/responses/Error"}}},"delete":{"summary":"Deletes the record with that externalId.","description":"It never changes a DeCA that has already been generated.\n\nRequired scope: saved:write.","parameters":[{"name":"externalId","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9._~:-]{1,100}$"},"description":"The record's identifier in your ERP or TMS."}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavedDeleted"}}}},"default":{"$ref":"#/components/responses/Error"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"The integration's API key."}},"schemas":{"Party":{"type":"object","additionalProperties":false,"required":["name","taxId","address"],"properties":{"name":{"type":"string","maxLength":200},"taxId":{"type":"string","maxLength":40,"description":"Tax identification number (Spanish NIF / VAT number)."},"country":{"type":"string","pattern":"^[A-Za-z]{2}$","description":"Country (ISO alpha-2). Defaults to Spain (ES)."},"address":{"type":"string","maxLength":300},"postalCode":{"type":"string","maxLength":12},"city":{"type":"string","maxLength":120}}},"Location":{"type":"object","additionalProperties":false,"required":["name","address","postalCode","city","country"],"properties":{"name":{"type":"string","maxLength":200},"address":{"type":"string","maxLength":300},"postalCode":{"type":"string","maxLength":12},"city":{"type":"string","maxLength":120},"province":{"type":"string","maxLength":120},"country":{"type":"string","pattern":"^[A-Za-z]{2}$","description":"ISO 3166-1 alpha-2 code (ES, FR, PT…)."}}},"Shipment":{"type":"object","additionalProperties":false,"required":["loadLocation","unloadLocation"],"properties":{"loadLocation":{"$ref":"#/components/schemas/Location"},"unloadLocation":{"$ref":"#/components/schemas/Location"},"goods":{"type":"string","maxLength":300,"description":"Nature of the goods."},"weight":{"description":"Weight or measure: a number (kg) or a text (e.g. \"12.000 kg\").","oneOf":[{"type":"number","exclusiveMinimum":0,"maximum":10000000},{"type":"string","maxLength":60}]},"recipient":{"type":"string","maxLength":200},"loadDate":{"type":"string","pattern":"^(\\d{2}-\\d{2}-\\d{4}|\\d{4}-\\d{2}-\\d{2})$","description":"Date DD-MM-YYYY (YYYY-MM-DD is also accepted).","examples":["06-10-2026"]},"unloadDate":{"type":"string","pattern":"^(\\d{2}-\\d{2}-\\d{4}|\\d{4}-\\d{2}-\\d{2})$","description":"Date DD-MM-YYYY (YYYY-MM-DD is also accepted).","examples":["06-10-2026"]},"tractorPlate":{"type":"string","maxLength":20},"trailerPlate":{"type":"string","maxLength":20},"notes":{"type":"string","maxLength":1000,"description":"Special information for the shipment. Multiple lines are allowed (line breaks)."}}},"CompletionRequest":{"type":"object","additionalProperties":false,"required":["recipientEmail","fields"],"properties":{"recipientEmail":{"type":"string","format":"email","maxLength":200},"recipientName":{"type":"string","maxLength":200},"recipientType":{"type":"string","enum":["shipper","carrier","authorized_person"]},"fields":{"type":"array","minItems":1,"maxItems":20,"items":{"type":"string","maxLength":80},"description":"Fields the third party completes, e.g. vehicle.tractorPlate, shipments[0].unloadLocation.city."},"expiresInHours":{"type":"integer","minimum":1,"maximum":48}}},"DecaCreate":{"type":"object","additionalProperties":false,"required":["loadDate","unloadDate","vehicle","shipper","carrier","shipments"],"properties":{"externalId":{"type":"string","pattern":"^[A-Za-z0-9._\\-/]{1,100}$","description":"Your identifier (order, consignment). Prevents duplicates: a second active DeCA with the same externalId answers 409."},"groupageRef":{"type":"string","pattern":"^[Gg]-[A-Za-z0-9]{6,16}$","description":"Optional: operational reference shared by the independent DeCA of a groupage (one DeCA per shipper). Filterable with GET /decas?groupageRef=…"},"serviceType":{"type":"string","enum":["goods","passenger"],"default":"goods"},"reference":{"type":"string","maxLength":120,"description":"DeCA reference / notes."},"notes":{"type":"string","maxLength":1000,"description":"Special information (default for every shipment). Multiple lines are allowed (line breaks)."},"loadDate":{"type":"string","pattern":"^(\\d{2}-\\d{2}-\\d{4}|\\d{4}-\\d{2}-\\d{2})$","description":"Date DD-MM-YYYY (YYYY-MM-DD is also accepted).","examples":["06-10-2026"]},"unloadDate":{"type":"string","pattern":"^(\\d{2}-\\d{2}-\\d{4}|\\d{4}-\\d{2}-\\d{2})$","description":"Date DD-MM-YYYY (YYYY-MM-DD is also accepted).","examples":["06-10-2026"]},"vehicle":{"type":"object","additionalProperties":false,"required":["tractorPlate"],"properties":{"tractorPlate":{"type":"string","maxLength":20},"trailerPlate":{"type":"string","maxLength":20},"secondTrailerPlate":{"type":"string","maxLength":20,"description":"Optional: second trailer/semi-trailer (double-trailer combinations). Requires trailerPlate and must differ from it."}}},"shipper":{"description":"Contractual shipper: \"self\" (your company) or its details.","oneOf":[{"const":"self"},{"$ref":"#/components/schemas/Party"}]},"carrier":{"description":"Actual carrier: \"self\" (your company) or its details.","oneOf":[{"const":"self"},{"$ref":"#/components/schemas/Party"}]},"shipments":{"type":"array","minItems":1,"maxItems":50,"items":{"$ref":"#/components/schemas/Shipment"}},"completionRequest":{"$ref":"#/components/schemas/CompletionRequest"},"draft":{"type":"boolean","description":"true: saves a draft instead of issuing the DeCA."},"loadOrder":{"type":"object","description":"Issues a load order WITH this DeCA (same rules as the web app): only if your company is the contractual shipper and the plan includes load orders.","properties":{"format":{"type":"string","enum":["joint","separate"]},"price":{"type":"string","description":"Amount, e.g. \"850,00\" (empty = no price)."},"currency":{"type":"string","enum":["EUR","USD","GBP","CHF"]},"taxNote":{"type":"string"},"conditions":{"type":"string"},"paymentTerms":{"type":"string"},"billingInstructions":{"type":"string"}},"required":["format"]}}},"Correction":{"type":"object","required":["changeReason","deca"],"properties":{"changeReason":{"type":"string","minLength":3,"maxLength":500},"baseVersionNo":{"type":"integer","minimum":1,"description":"The version you are correcting (prevents concurrent corrections: 409)."},"deca":{"$ref":"#/components/schemas/DecaCreate"}}},"Annulment":{"type":"object","required":["reason"],"properties":{"reason":{"type":"string","minLength":3,"maxLength":500}}},"VehicleChange":{"type":"object","additionalProperties":false,"required":["tractorPlate","effectiveAt"],"properties":{"tractorPlate":{"type":"string","maxLength":20},"trailerPlate":{"type":"string","maxLength":20},"effectiveAt":{"type":"string","pattern":"^(\\d{2}-\\d{2}-\\d{4}|\\d{4}-\\d{2}-\\d{2})$","description":"Date DD-MM-YYYY (YYYY-MM-DD is also accepted).","examples":["06-10-2026"]},"reason":{"type":"string","maxLength":200}}},"CompletionResendRequest":{"type":"object","properties":{"expiresInHours":{"type":"integer","minimum":1,"maximum":48}}},"DraftCreate":{"type":"object","description":"Any subset of the DecaCreate fields (without completionRequest or draft).","properties":{"externalId":{"type":"string","pattern":"^[A-Za-z0-9._\\-/]{1,100}$"},"reference":{"type":"string","maxLength":120},"loadDate":{"type":"string","pattern":"^(\\d{2}-\\d{2}-\\d{4}|\\d{4}-\\d{2}-\\d{2})$","description":"Date DD-MM-YYYY (YYYY-MM-DD is also accepted).","examples":["06-10-2026"]},"unloadDate":{"type":"string","pattern":"^(\\d{2}-\\d{2}-\\d{4}|\\d{4}-\\d{2}-\\d{2})$","description":"Date DD-MM-YYYY (YYYY-MM-DD is also accepted).","examples":["06-10-2026"]},"vehicle":{"type":"object"},"shipper":{},"carrier":{},"shipments":{"type":"array","items":{"type":"object"}}}},"DraftPatch":{"type":"object","description":"JSON Merge Patch (RFC 7386) applied to the draft."},"DecaStatus":{"type":"object","required":["id","reference","status","availability","version","createdAt","updatedAt"],"properties":{"id":{"type":"string"},"reference":{"type":["string","null"],"examples":["DECA-A4F2C9E1"]},"externalId":{"type":["string","null"]},"groupageRef":{"type":["string","null"]},"status":{"type":"string","enum":["active","annulled"]},"availability":{"type":"string","enum":["public","expired","annulled"]},"version":{"type":["integer","null"]},"createdAt":{"type":"string","description":"ISO 8601 with the Europe/Madrid offset, e.g. 2026-10-08T10:41:00+02:00.","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{2}:\\d{2}$"},"updatedAt":{"type":"string","description":"ISO 8601 with the Europe/Madrid offset, e.g. 2026-10-08T10:41:00+02:00.","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{2}:\\d{2}$"},"annulledAt":{"type":["string","null"],"description":"ISO 8601 with the Europe/Madrid offset, e.g. 2026-10-08T10:41:00+02:00.","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{2}:\\d{2}$"},"service":{"type":"object","properties":{"finished":{"type":"boolean"},"finishedAt":{"type":["string","null"],"description":"ISO 8601 with the Europe/Madrid offset, e.g. 2026-10-08T10:41:00+02:00.","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{2}:\\d{2}$"},"note":{"type":["string","null"]}}},"verificationUrl":{"type":["string","null"],"format":"uri"}}},"ServiceCompletion":{"type":"object","additionalProperties":false,"properties":{"note":{"type":"string","maxLength":500,"description":"Optional remark."}}},"LoadOrder":{"type":"object","required":["id","number","status","format"],"properties":{"id":{"type":"string"},"number":{"type":"string"},"status":{"type":"string","enum":["pending_vehicle","active","cancelled"]},"format":{"type":"string","enum":["joint","separate"]},"reference":{"type":["string","null"]},"carrierName":{"type":["string","null"]},"loadDate":{"type":["string","null"],"pattern":"^\\d{2}-\\d{2}-\\d{4}$","description":"DD-MM-YYYY"},"deca":{"type":["object","null"],"properties":{"id":{"type":"string"},"status":{"type":"string","enum":["active","annulled"]}}},"platesPending":{"type":"boolean"},"version":{"type":["object","null"],"properties":{"number":{"type":"integer"},"kind":{"type":"string"},"createdAt":{"type":"string","description":"ISO 8601 with the Europe/Madrid offset, e.g. 2026-10-08T10:41:00+02:00.","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{2}:\\d{2}$"},"pdfSha256":{"type":["string","null"]}}},"acceptance":{"type":["object","null"],"properties":{"versionNo":{"type":"integer"},"acceptedAt":{"type":"string","description":"ISO 8601 with the Europe/Madrid offset, e.g. 2026-10-08T10:41:00+02:00.","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{2}:\\d{2}$"}}},"createdAt":{"type":"string","description":"ISO 8601 with the Europe/Madrid offset, e.g. 2026-10-08T10:41:00+02:00.","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{2}:\\d{2}$"},"links":{"type":"object","additionalProperties":{"type":"string"}}}},"LoadOrderList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/LoadOrder"}}}},"Deca":{"type":"object","required":["id","status","verification","pdf","links"],"properties":{"id":{"type":"string"},"reference":{"type":["string","null"]},"externalId":{"type":["string","null"]},"groupageRef":{"type":["string","null"],"description":"Operational groupage reference (G-…), shared by the independent DeCA of one operation."},"status":{"type":"string","enum":["active","annulled"]},"availability":{"type":"string","enum":["public","expired","annulled"]},"version":{"type":["integer","null"]},"createdAt":{"type":"string","description":"ISO 8601 with the Europe/Madrid offset, e.g. 2026-10-08T10:41:00+02:00.","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{2}:\\d{2}$"},"updatedAt":{"type":"string","description":"ISO 8601 with the Europe/Madrid offset, e.g. 2026-10-08T10:41:00+02:00.","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{2}:\\d{2}$"},"annulledAt":{"type":["string","null"],"description":"ISO 8601 with the Europe/Madrid offset, e.g. 2026-10-08T10:41:00+02:00.","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{2}:\\d{2}$"},"service":{"type":"object","description":"OPERATIONAL service-finished flag; it never changes the administrative status, the PDF or the URL.","properties":{"finished":{"type":"boolean"},"finishedAt":{"type":["string","null"],"description":"ISO 8601 with the Europe/Madrid offset, e.g. 2026-10-08T10:41:00+02:00.","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{2}:\\d{2}$"},"note":{"type":["string","null"]}}},"serviceType":{"type":"string","enum":["goods","passenger"]},"servicePeriod":{"type":"object","properties":{"start":{"type":["string","null"],"pattern":"^\\d{2}-\\d{2}-\\d{4}$","description":"DD-MM-YYYY"},"end":{"type":["string","null"],"pattern":"^\\d{2}-\\d{2}-\\d{4}$","description":"DD-MM-YYYY"},"publicUntil":{"type":["string","null"],"pattern":"^\\d{2}-\\d{2}-\\d{4}$","description":"DD-MM-YYYY"}}},"verification":{"type":"object","properties":{"url":{"type":["string","null"],"format":"uri"},"note":{"type":"string"}}},"pdf":{"type":"object","properties":{"href":{"type":"string"},"sha256":{"type":["string","null"]},"contentType":{"const":"application/pdf"}}},"data":{"type":["object","null"],"description":"DeCA content (parties, vehicle, shipments); dates DD-MM-YYYY."},"warnings":{"type":"array","items":{"type":"string"}},"links":{"type":"object","additionalProperties":{"type":"string"}}}},"DecaList":{"type":"object","required":["data","nextCursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DecaListItem"}},"nextCursor":{"type":["string","null"]}}},"DecaListItem":{"type":"object","description":"A DeCA in the list: the lightweight status (as in GET /decas/{id}/status), the verification URL, a summary and the links. The full content is at GET /decas/{id}.","required":["id","reference","status","availability","version","createdAt","updatedAt","verificationUrl","summary","links"],"properties":{"id":{"type":"string"},"reference":{"type":["string","null"],"examples":["DECA-A4F2C9E1"]},"externalId":{"type":["string","null"]},"groupageRef":{"type":["string","null"]},"status":{"type":"string","enum":["active","annulled"]},"availability":{"type":"string","enum":["public","expired","annulled"]},"version":{"type":["integer","null"]},"createdAt":{"type":"string","description":"ISO 8601 with the Europe/Madrid offset, e.g. 2026-10-08T10:41:00+02:00.","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{2}:\\d{2}$"},"updatedAt":{"type":"string","description":"ISO 8601 with the Europe/Madrid offset, e.g. 2026-10-08T10:41:00+02:00.","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{2}:\\d{2}$"},"annulledAt":{"type":["string","null"],"description":"ISO 8601 with the Europe/Madrid offset, e.g. 2026-10-08T10:41:00+02:00.","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{2}:\\d{2}$"},"service":{"type":"object","properties":{"finished":{"type":"boolean"},"finishedAt":{"type":["string","null"],"description":"ISO 8601 with the Europe/Madrid offset, e.g. 2026-10-08T10:41:00+02:00.","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{2}:\\d{2}$"},"note":{"type":["string","null"]}}},"verificationUrl":{"type":["string","null"],"format":"uri"},"summary":{"type":["object","null"],"properties":{"shipper":{"type":["string","null"],"description":"Shipper name."},"carrier":{"type":["string","null"],"description":"Carrier name."},"tractorPlate":{"type":["string","null"]},"loadDate":{"type":["string","null"],"pattern":"^\\d{2}-\\d{2}-\\d{4}$","description":"DD-MM-YYYY"},"shipmentCount":{"type":"integer"}}},"links":{"type":"object","additionalProperties":{"type":"string"}}}},"Validation":{"type":"object","required":["valid","warnings"],"properties":{"valid":{"const":true},"warnings":{"type":"array","items":{"type":"string"}}}},"VersionList":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","required":["version","current","createdAt","actorType","verificationUrl","pdf"],"properties":{"version":{"type":"integer"},"current":{"type":"boolean"},"createdAt":{"type":"string","description":"ISO 8601 with the Europe/Madrid offset, e.g. 2026-10-08T10:41:00+02:00.","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{2}:\\d{2}$"},"changeReason":{"type":["string","null"]},"actorType":{"type":"string","enum":["api","user","anonymous"]},"verificationUrl":{"type":"string","format":"uri"},"pdf":{"type":"object","properties":{"href":{"type":"string"},"sha256":{"type":["string","null"]}}}}}}}},"VehicleList":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["initial","change"]},"tractorPlate":{"type":"string"},"trailerPlate":{"type":["string","null"]},"effectiveAt":{"type":["string","null"],"pattern":"^\\d{2}-\\d{2}-\\d{4}$","description":"DD-MM-YYYY"},"reason":{"type":["string","null"]},"current":{"type":"boolean"}}}}}},"Me":{"type":"object","required":["credential","company","access","limits","usage"],"properties":{"credential":{"type":"object","properties":{"name":{"type":"string"},"key":{"type":"string","description":"Masked key: the secret is never returned."},"mode":{"type":"string","enum":["live","test"],"description":"test = test key (fvd_test_)."},"scopes":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string","description":"ISO 8601 with the Europe/Madrid offset, e.g. 2026-10-08T10:41:00+02:00.","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{2}:\\d{2}$"},"expiresAt":{"type":["string","null"],"description":"ISO 8601 with the Europe/Madrid offset, e.g. 2026-10-08T10:41:00+02:00.","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{2}:\\d{2}$"}}},"company":{"type":"object","properties":{"name":{"type":"string"},"taxId":{"type":["string","null"]}}},"access":{"type":"object","properties":{"plan":{"type":"string","description":"The company's plan."},"businessEligible":{"type":"boolean","description":"The plan allows API access."},"apiEntitlement":{"type":"string","enum":["paid","manual","none"],"description":"Source of the API access."},"paidAddon":{"type":"string","enum":["active","cancelling","inactive"],"description":"Status of the API add-on."},"manualGrant":{"type":"string","enum":["active","expired","ended","none"]}}},"limits":{"type":"object","properties":{"requestsPerMinute":{"type":"integer"},"createsPerDay":{"type":"integer"}}},"usage":{"type":"object","properties":{"decasThisMonth":{"type":"integer","description":"DeCA created in the current plan period (API and dashboard share the allowance)."},"planMonthlyLimit":{"type":["integer","null"],"description":"Monthly plan allowance (null = unlimited)."},"remainingThisMonth":{"type":["integer","null"]},"decasThisPeriod":{"type":"integer"},"remainingThisPeriod":{"type":["integer","null"]},"periodStart":{"type":["string","null"],"description":"ISO 8601 with the Europe/Madrid offset, e.g. 2026-10-08T10:41:00+02:00.","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{2}:\\d{2}$"},"periodEnd":{"type":["string","null"],"description":"ISO 8601 with the Europe/Madrid offset, e.g. 2026-10-08T10:41:00+02:00.","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{2}:\\d{2}$"}}}}},"Draft":{"type":"object","required":["id","status"],"properties":{"id":{"type":"string"},"draftId":{"type":"string"},"object":{"type":"string","enum":["api_draft","draft"],"description":"api_draft = created through the API; draft = draft started in the web app."},"origin":{"type":"string","enum":["api","web"]},"status":{"type":"string","enum":["open","generated","cancelled"]},"version":{"type":"integer","description":"Draft version (ETag \"<id>.<version>\")."},"externalId":{"type":["string","null"]},"data":{"type":"object"},"ready":{"type":"boolean","description":"Only on open drafts read one by one: true if the DeCA can be generated now."},"warnings":{"type":"array","items":{"type":"string"}},"issues":{"type":"array","description":"What is missing or invalid (empty when ready is true).","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"createdBy":{"type":["string","null"],"description":"Web drafts only."},"updatedBy":{"type":["string","null"],"description":"Web drafts only."},"decaId":{"type":["string","null"]},"generatedAt":{"type":["string","null"],"description":"ISO 8601 with the Europe/Madrid offset, e.g. 2026-10-08T10:41:00+02:00.","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{2}:\\d{2}$"},"cancelledAt":{"type":["string","null"],"description":"ISO 8601 with the Europe/Madrid offset, e.g. 2026-10-08T10:41:00+02:00.","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{2}:\\d{2}$"},"createdAt":{"type":"string","description":"ISO 8601 with the Europe/Madrid offset, e.g. 2026-10-08T10:41:00+02:00.","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{2}:\\d{2}$"},"updatedAt":{"type":"string","description":"ISO 8601 with the Europe/Madrid offset, e.g. 2026-10-08T10:41:00+02:00.","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{2}:\\d{2}$"},"links":{"type":"object","additionalProperties":{"type":"string"}}}},"DraftList":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Draft"}},"nextCursor":{"type":["string","null"]}}},"WebhookEvent":{"type":"object","required":["id","type","createdAt","livemode","data"],"description":"Notification sent to your endpoint. Headers: DeCA-Event-Id, DeCA-Event-Type, DeCA-Signature (t=<s>,v1=<HMAC-SHA256 hex of \"<t>.<body>\">).","properties":{"id":{"type":"string","description":"Identical across retries: use it to discard duplicates."},"type":{"type":"string","enum":["deca.created","deca.corrected","deca.annulled","draft.generated","completion.completed","deca.service_finished","deca.service_reopened","load_order.issued","load_order.accepted","webhook.test"]},"createdAt":{"type":"string","description":"ISO 8601 with the Europe/Madrid offset, e.g. 2026-10-08T10:41:00+02:00.","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{2}:\\d{2}$"},"livemode":{"type":"boolean"},"data":{"type":"object"}}},"CompletionRequestResult":{"type":"object","description":"Draft with its third-party completion request (status, recipient, expiry)."},"SavedCompanyInput":{"type":"object","additionalProperties":false,"required":["name","taxId","address","postalCode","city"],"properties":{"name":{"type":"string","minLength":2,"maxLength":200},"taxId":{"type":"string","minLength":3,"maxLength":20},"address":{"type":"string","minLength":4,"maxLength":300},"postalCode":{"type":"string","minLength":3,"maxLength":12},"city":{"type":"string","minLength":2,"maxLength":120},"role":{"type":"string","enum":["shipper","carrier","both"]}}},"SavedVehicleInput":{"type":"object","additionalProperties":false,"required":["tractorPlate"],"properties":{"tractorPlate":{"type":"string","minLength":2,"maxLength":20},"trailerPlate":{"type":"string","maxLength":20},"alias":{"type":"string","maxLength":80},"habitualDriver":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string","maxLength":200},"phone":{"type":"string","maxLength":40},"email":{"type":"string","maxLength":200}}}}},"SavedPlaceInput":{"type":"object","additionalProperties":false,"required":["name","address","postalCode","city"],"properties":{"name":{"type":"string","minLength":2,"maxLength":200},"address":{"type":"string","minLength":4,"maxLength":300},"postalCode":{"type":"string","minLength":3,"maxLength":12},"city":{"type":"string","minLength":2,"maxLength":120},"province":{"type":"string","maxLength":120},"country":{"type":"string","maxLength":80},"type":{"type":"string","enum":["load","unload","both"]}}},"SavedShipmentInput":{"type":"object","additionalProperties":false,"required":["loadPlaceExternalId","unloadPlaceExternalId"],"properties":{"name":{"type":"string","maxLength":200},"loadPlaceExternalId":{"type":"string","pattern":"^[A-Za-z0-9._~:-]{1,100}$"},"unloadPlaceExternalId":{"type":"string","pattern":"^[A-Za-z0-9._~:-]{1,100}$"},"goods":{"type":"string","maxLength":300},"weight":{"type":"string","maxLength":60},"recipient":{"type":"string","maxLength":200}}},"SavedRecord":{"type":"object","description":"A Saved data record: id, externalId (null if it was created in the web app), createdAt and the resource fields (those of its *Input; shipments return loadPlace and unloadPlace with id, externalId and name).","properties":{"id":{"type":"string"},"externalId":{"type":["string","null"]},"createdAt":{"type":"string","description":"ISO 8601 with the Europe/Madrid offset, e.g. 2026-10-08T10:41:00+02:00.","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{2}:\\d{2}$"}}},"SavedList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SavedRecord"}},"nextCursor":{"type":["string","null"]}}},"SavedDeleted":{"type":"object","properties":{"deleted":{"type":"boolean","const":true},"externalId":{"type":"string"}}},"BatchCreate":{"type":"object","required":["items"],"properties":{"items":{"type":"array","minItems":1,"maxItems":50,"items":{"$ref":"#/components/schemas/DecaCreate"}}}},"Batch":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["processing","completed"]},"total":{"type":"integer"},"counts":{"type":"object","additionalProperties":{"type":"integer"}},"createdAt":{"type":"string","description":"ISO 8601 with the Europe/Madrid offset, e.g. 2026-10-08T10:41:00+02:00.","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{2}:\\d{2}$"},"completedAt":{"type":["string","null"],"description":"ISO 8601 with the Europe/Madrid offset, e.g. 2026-10-08T10:41:00+02:00.","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{2}:\\d{2}$"},"items":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"externalId":{"type":["string","null"]},"status":{"type":"string","enum":["pending","processing","created","replayed","failed"]},"decaId":{"type":["string","null"]},"error":{"type":["object","null"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}},"links":{"type":"object","properties":{"self":{"type":"string"},"pdfs":{"type":"string"}}}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string","description":"Stable error code: branch your integration on it."},"message":{"type":"string","description":"Informative message: Spanish by default, English with `Accept-Language: en`. Never parse it."},"requestId":{"type":"string"},"details":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}}}}},"responses":{"Error":{"description":"Error. Possible codes:\n\n- **400** `invalid_json, idempotency_key_required, invalid_query`: Malformed request, missing Idempotency-Key, or an invalid filter.\n- **401** `invalid_credentials, credential_revoked, credential_expired`: Unknown or incorrect key (the same response in both cases), revoked or expired.\n- **402** `business_plan_required, plan_allowance_exhausted`: The company's plan does not include the API, or the plan's DeCA allowance is used up.\n- **403** `api_addon_required, api_advanced_required, professional_plan_required, company_inactive, ip_not_allowed, insufficient_scope, sandbox_not_supported`: The API add-on is not active, the account is not active, the IP address is not authorised, the permission is insufficient, or the endpoint is not available with a test key.\n- **429** `api_lite_limit_reached`: API Lite: the 100 DeCAs of the month have already been created through the API (within the plan allowance). It renews with the plan period; for more, API Advanced.\n- **404** `not_found`: It does not exist or is not visible to this credential (the two cases are never distinguished).\n- **409** `duplicate_external_id, idempotency_conflict, deca_annulled, version_conflict, batch_without_documents, saved_in_use, company_inactive`: externalId already used by an active DeCA (includes existingId), idempotency key reused with a different body, annulled DeCA, concurrent correction, batch that has not created any DeCA yet, saved place used by a saved shipment, or the company has no Administrator when syncing saved data.\n- **402 / 403 / 409 / 422** `load_order_plan_required, load_order_not_shipper, load_order_company_nif_missing, load_order_invalid, load_order_passenger`: Load order with POST /decas (loadOrder): the plan does not include load orders (402), your company is not the contractual shipper (403), your company's tax ID (NIF) is missing (409), the commercial data is not valid (422, details points to the field under /loadOrder/…) or the service is a passenger service (422). No DeCA is created.\n- **409** `deca_already_issued, completion_request_pending, completion_request_completed, draft_cancelled`: Third-party requests: the DeCA is already in force (use a correction), a request is already pending (use /resend), the request has already been completed, or the draft was cancelled.\n- **409** `draft_not_open, draft_limit_reached, draft_has_preparation, completion_request_no_email`: Drafts: already generated or cancelled, limit of open drafts reached (includes limit), web draft linked to a third-party request (generate it with /api/v1/decas/{id}), or the request has no recipient email.\n- **412** `precondition_failed`: If-Match does not match: the draft has changed since you last read it. Read it again (ETag header) and reapply your change.\n- **404** `completion_request_not_found`: Resend requested for a DeCA without any third-party request.\n- **422** `invalid_draft, invalid_completion_request, new_service_required`: The draft or the change is not a valid JSON object (or includes fields only allowed in POST /decas), the third-party request is not valid, or the correction changes the service (create a new DeCA).\n- **413 / 415** `payload_too_large, unsupported_media_type`: Body larger than 256 KB, or not application/json.\n- **422** `validation`: Invalid data. details lists each field with a JSON Pointer and a code (required, unknown_field, invalid_country, too_short, too_long, invalid_format, invalid_value, self_company_incomplete…). The message is informative only (Spanish by default; it can be requested in English with Accept-Language: en): integrations must branch on code.\n- **422** `invalid_completion_field`: A field in completionRequest.fields cannot be requested from a third party (unknown_field) or refers to a shipment that does not exist (unknown_shipment).\n- **429** `rate_limited, daily_create_ceiling, too_many_failed_attempts`: Request limit exceeded. Respect the Retry-After header.\n- **500** `generation_failed, internal_error`: Generation error (includes correlationId and retryable: retry with the same Idempotency-Key) or internal error.\n- **503** `service_unavailable, pdf_unavailable`: Service or PDF temporarily unavailable: retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"validation","message":"The DeCA does not meet the mandatory requirements.","requestId":"req_7f3a9c…","details":[{"path":"/shipments/0/unloadLocation/country","code":"invalid_country","message":"Use an ISO 3166-1 alpha-2 country code (e.g. ES, FR, PT)"}]}}}}}}}}