{ "openapi": "3.1.0", "info": { "title": "DeCA Profesional API", "version": "1", "description": "DeCA Profesional REST API — API Lite (Professional plan + API Lite add-on, €39.95/month + VAT): validate, create, read, correct and annul DeCA. 100 DeCA per month through the API, within the plan allowance, 1 key, 20 requests per minute.\n\nAuthentication: header `Authorization: Bearer `. 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" } } } }, "/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}/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}/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" } } } } }, "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 \".\")." }, "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=,v1=.\">).", "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)" } ] } } } } } } } }