{ "openapi": "3.1.0", "info": { "title": "API de DeCA Profesional", "version": "1", "description": "API REST de DeCA Profesional — API Lite (plan Professional + complemento API Lite, 39,95 €/mes + IVA): validar, crear, consultar, corregir y anular DeCA. 100 DeCA por API al mes dentro del cupo del plan, 1 clave, 20 peticiones por minuto.\n\nAutenticación: cabecera `Authorization: Bearer `. Las claves solo se muestran una vez; nunca las uses en el navegador.\n\nFechas en DD-MM-AAAA y horas en hora de Madrid (ISO 8601 con su desfase, p. ej. 2026-10-08T10:41:00+02:00).\n\nLímites: 60 peticiones/minuto por clave, cuerpo máximo 256 KB, hasta 50 envíos por DeCA.\n\nPermisos de una clave:\n- `deca:create`: Crear DeCA (POST /decas, también por lotes) y validarlos (POST /decas/validate), crear, modificar y generar borradores, y pedir datos a un tercero.\n- `deca:read`: Leer y listar los DeCA creados por esta integración, sus borradores, lotes y órdenes de carga.\n- `deca:read_company`: Ampliar la lectura a todos los DeCA de la empresa. Nunca amplía la escritura.\n- `deca:correct`: Corregir DeCA creados por esta integración, registrar cambios de vehículo y marcar o reabrir el servicio finalizado.\n- `deca:annul`: Anular DeCA creados por esta integración.\n- `saved:read`: Leer los datos habituales de la empresa: empresas, vehículos, lugares y envíos habituales.\n- `saved:write`: Crear, actualizar (PUT por externalId) y borrar datos habituales desde tu ERP o 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": "Responde 2xx en menos de 10 s; si no, se reintenta durante 24 h." } } } }, "deca.corrected": { "post": { "summary": "deca.corrected", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "200": { "description": "Responde 2xx en menos de 10 s; si no, se reintenta durante 24 h." } } } }, "deca.annulled": { "post": { "summary": "deca.annulled", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "200": { "description": "Responde 2xx en menos de 10 s; si no, se reintenta durante 24 h." } } } }, "draft.generated": { "post": { "summary": "draft.generated", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "200": { "description": "Responde 2xx en menos de 10 s; si no, se reintenta durante 24 h." } } } }, "completion.completed": { "post": { "summary": "completion.completed", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "200": { "description": "Responde 2xx en menos de 10 s; si no, se reintenta durante 24 h." } } } }, "deca.service_finished": { "post": { "summary": "deca.service_finished", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "200": { "description": "Responde 2xx en menos de 10 s; si no, se reintenta durante 24 h." } } } }, "deca.service_reopened": { "post": { "summary": "deca.service_reopened", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "200": { "description": "Responde 2xx en menos de 10 s; si no, se reintenta durante 24 h." } } } }, "load_order.issued": { "post": { "summary": "load_order.issued", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "200": { "description": "Responde 2xx en menos de 10 s; si no, se reintenta durante 24 h." } } } }, "load_order.accepted": { "post": { "summary": "load_order.accepted", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "200": { "description": "Responde 2xx en menos de 10 s; si no, se reintenta durante 24 h." } } } } }, "security": [ { "bearerAuth": [] } ], "paths": { "/api/v1/me": { "get": { "summary": "Comprueba la credencial: integración, empresa, permisos, límites y uso del mes.", "description": "El primer endpoint que debes llamar para verificar la conexión.\n\nNo requiere permiso específico.", "parameters": [], "responses": { "200": { "description": "Correcto.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Me" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/decas/validate": { "post": { "summary": "Valida un DeCA sin crearlo: mismas reglas que la creación.", "description": "No crea ningún DeCA, no genera PDF y no consume el cupo del plan.\n\nPermiso necesario: 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": "Correcto.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Validation" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/decas": { "post": { "summary": "Crea un DeCA y devuelve la URL de verificación, la referencia y el PDF.", "description": "Responde 201 (o 200 si es un reintento con la misma Idempotency-Key). Con completionRequest (o draft: true) crea un borrador y responde 202: ver «Completar un DeCA por un tercero».\n\nPermiso necesario: deca:create.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 255 }, "description": "Clave única por operación (8–255 caracteres). Un reintento con la misma clave y el mismo cuerpo devuelve el mismo resultado." } ], "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": "Reintento con la misma Idempotency-Key y el mismo cuerpo: el resultado original (cabecera 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": "Correcto.", "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": "Con completionRequest o draft: true: borrador creado (y, en su caso, solicitud a un tercero enviada).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompletionRequestResult" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/decas/{id}": { "get": { "summary": "El DeCA completo: estado, periodo del servicio, URL de verificación, PDF y datos.", "description": "Permiso necesario: deca:read.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identificador del DeCA." } ], "responses": { "200": { "description": "Correcto.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deca" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/decas/{id}/status": { "get": { "summary": "Estado ligero (versión, disponibilidad, URL de verificación) para consultas periódicas.", "description": "Permiso necesario: deca:read.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identificador del DeCA." } ], "responses": { "200": { "description": "Correcto.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecaStatus" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/decas/{id}/pdf": { "get": { "summary": "Descarga el PDF (versión vigente o ?version=N).", "description": "Cabeceras X-Pdf-Sha256 (huella del PDF) y X-Deca-Status (active | annulled).\n\nPermiso necesario: deca:read.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identificador del DeCA." }, { "name": "version", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "Número de versión (por defecto, la vigente)." } ], "responses": { "200": { "description": "Correcto.", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/decas/{id}/corrections": { "post": { "summary": "Corrige un DeCA: crea una nueva versión con nueva URL, QR y PDF.", "description": "Responde 201 con la nueva versión (200 si es un reintento con la misma Idempotency-Key). Solo DeCA creados por la misma integración; las versiones anteriores se conservan.\n\nPermiso necesario: deca:correct.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identificador del DeCA." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 255 }, "description": "Clave única por operación (8–255 caracteres). Un reintento con la misma clave y el mismo cuerpo devuelve el mismo resultado." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Correction" }, "example": { "changeReason": "Cambio de matrícula del remolque", "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": "Reintento con la misma Idempotency-Key y el mismo cuerpo: el resultado original (cabecera 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": "Correcto.", "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": "Anula un DeCA. Es definitivo; repetir la llamada devuelve 200 sin cambios.", "description": "Solo DeCA creados por la misma integración.\n\nPermiso necesario: deca:annul.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identificador del DeCA." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Annulment" }, "example": { "reason": "Pedido cancelado por el cliente" } } } }, "responses": { "200": { "description": "Correcto.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deca" } } } }, "default": { "$ref": "#/components/responses/Error" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Clave de API de la integración." } }, "schemas": { "Party": { "type": "object", "additionalProperties": false, "required": [ "name", "taxId", "address" ], "properties": { "name": { "type": "string", "maxLength": 200 }, "taxId": { "type": "string", "maxLength": 40, "description": "NIF / VAT" }, "country": { "type": "string", "pattern": "^[A-Za-z]{2}$", "description": "País (ISO alfa-2). Por defecto, España." }, "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": "Código ISO 3166-1 alfa-2 (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": "Naturaleza de la mercancía." }, "weight": { "description": "Peso o medida: un número (kg) o un texto (p. ej. \"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": "Fecha DD-MM-AAAA (también se acepta AAAA-MM-DD).", "examples": [ "06-10-2026" ] }, "unloadDate": { "type": "string", "pattern": "^(\\d{2}-\\d{2}-\\d{4}|\\d{4}-\\d{2}-\\d{2})$", "description": "Fecha DD-MM-AAAA (también se acepta AAAA-MM-DD).", "examples": [ "06-10-2026" ] }, "tractorPlate": { "type": "string", "maxLength": 20 }, "trailerPlate": { "type": "string", "maxLength": 20 }, "notes": { "type": "string", "maxLength": 1000, "description": "Información especial del envío. Admite varias líneas (saltos de línea)." } } }, "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": "Campos que completa el tercero, p. ej. 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": "Tu identificador (pedido, expedición). Evita duplicados: un segundo DeCA activo con el mismo externalId responde 409." }, "groupageRef": { "type": "string", "pattern": "^[Gg]-[A-Za-z0-9]{6,16}$", "description": "S-1905 — opcional: referencia operativa común a los DeCA independientes de un grupaje (un DeCA por cargador). Se puede filtrar con GET /decas?groupageRef=…" }, "serviceType": { "type": "string", "enum": [ "goods", "passenger" ], "default": "goods" }, "reference": { "type": "string", "maxLength": 120, "description": "Referencia / notas del DeCA." }, "notes": { "type": "string", "maxLength": 1000, "description": "Información especial (por defecto de todos los envíos). Admite varias líneas (saltos de línea)." }, "loadDate": { "type": "string", "pattern": "^(\\d{2}-\\d{2}-\\d{4}|\\d{4}-\\d{2}-\\d{2})$", "description": "Fecha DD-MM-AAAA (también se acepta AAAA-MM-DD).", "examples": [ "06-10-2026" ] }, "unloadDate": { "type": "string", "pattern": "^(\\d{2}-\\d{2}-\\d{4}|\\d{4}-\\d{2}-\\d{2})$", "description": "Fecha DD-MM-AAAA (también se acepta AAAA-MM-DD).", "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": "Opcional: segundo remolque/semirremolque (conjuntos de dos remolques). Requiere trailerPlate y debe ser distinta." } } }, "shipper": { "description": "Cargador contractual: \"self\" (tu empresa) o sus datos.", "oneOf": [ { "const": "self" }, { "$ref": "#/components/schemas/Party" } ] }, "carrier": { "description": "Transportista efectivo: \"self\" (tu empresa) o sus datos.", "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: guarda un borrador en lugar de emitir el DeCA." }, "loadOrder": { "type": "object", "description": "S-1908 — emite una orden de carga CON este DeCA (mismas reglas que la web): solo si tu empresa es el cargador contractual y el plan incluye la orden de carga.", "properties": { "format": { "type": "string", "enum": [ "joint", "separate" ] }, "price": { "type": "string", "description": "Importe, p. ej. \"850,00\" (vacío = sin precio)." }, "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": "Versión que estás corrigiendo (evita correcciones simultáneas: 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": "Fecha DD-MM-AAAA (también se acepta AAAA-MM-DD).", "examples": [ "06-10-2026" ] }, "reason": { "type": "string", "maxLength": 200 } } }, "CompletionResendRequest": { "type": "object", "properties": { "expiresInHours": { "type": "integer", "minimum": 1, "maximum": 48 } } }, "DraftCreate": { "type": "object", "description": "Cualquier subconjunto de los campos de DecaCreate (sin completionRequest ni 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": "Fecha DD-MM-AAAA (también se acepta AAAA-MM-DD).", "examples": [ "06-10-2026" ] }, "unloadDate": { "type": "string", "pattern": "^(\\d{2}-\\d{2}-\\d{4}|\\d{4}-\\d{2}-\\d{2})$", "description": "Fecha DD-MM-AAAA (también se acepta AAAA-MM-DD).", "examples": [ "06-10-2026" ] }, "vehicle": { "type": "object" }, "shipper": {}, "carrier": {}, "shipments": { "type": "array", "items": { "type": "object" } } } }, "DraftPatch": { "type": "object", "description": "JSON Merge Patch (RFC 7386) sobre el borrador." }, "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 con el desfase de Madrid, p. ej. 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 con el desfase de Madrid, p. ej. 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 con el desfase de Madrid, p. ej. 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 con el desfase de Madrid, p. ej. 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": "Observación opcional." } } }, "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-AAAA" }, "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 con el desfase de Madrid, p. ej. 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 con el desfase de Madrid, p. ej. 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 con el desfase de Madrid, p. ej. 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": "S-1905 — referencia operativa del grupaje (G-…), común a los DeCA independientes de una misma operación." }, "status": { "type": "string", "enum": [ "active", "annulled" ] }, "availability": { "type": "string", "enum": [ "public", "expired", "annulled" ] }, "version": { "type": [ "integer", "null" ] }, "createdAt": { "type": "string", "description": "ISO 8601 con el desfase de Madrid, p. ej. 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 con el desfase de Madrid, p. ej. 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 con el desfase de Madrid, p. ej. 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": "S-1903 — marca OPERATIVA de servicio finalizado; nunca cambia el estado administrativo, el PDF ni la URL.", "properties": { "finished": { "type": "boolean" }, "finishedAt": { "type": [ "string", "null" ], "description": "ISO 8601 con el desfase de Madrid, p. ej. 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-AAAA" }, "end": { "type": [ "string", "null" ], "pattern": "^\\d{2}-\\d{2}-\\d{4}$", "description": "DD-MM-AAAA" }, "publicUntil": { "type": [ "string", "null" ], "pattern": "^\\d{2}-\\d{2}-\\d{4}$", "description": "DD-MM-AAAA" } } }, "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": "Contenido del DeCA (partes, vehículo, envíos); fechas DD-MM-AAAA." }, "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": "Un DeCA del listado: el estado ligero (como GET /decas/{id}/status), la URL de verificación, un resumen y los enlaces. El contenido completo está en 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 con el desfase de Madrid, p. ej. 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 con el desfase de Madrid, p. ej. 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 con el desfase de Madrid, p. ej. 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 con el desfase de Madrid, p. ej. 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": "Nombre del cargador." }, "carrier": { "type": [ "string", "null" ], "description": "Nombre del transportista." }, "tractorPlate": { "type": [ "string", "null" ] }, "loadDate": { "type": [ "string", "null" ], "pattern": "^\\d{2}-\\d{2}-\\d{4}$", "description": "DD-MM-AAAA" }, "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 con el desfase de Madrid, p. ej. 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-AAAA" }, "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": "Clave enmascarada: nunca se devuelve el secreto." }, "mode": { "type": "string", "enum": [ "live", "test" ], "description": "test = clave de pruebas (fvd_test_)." }, "scopes": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "description": "ISO 8601 con el desfase de Madrid, p. ej. 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 con el desfase de Madrid, p. ej. 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": "Plan de la empresa." }, "businessEligible": { "type": "boolean", "description": "El plan permite la API." }, "apiEntitlement": { "type": "string", "enum": [ "paid", "manual", "none" ], "description": "Origen del acceso a la API." }, "paidAddon": { "type": "string", "enum": [ "active", "cancelling", "inactive" ], "description": "Estado del complemento API." }, "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 creados en el periodo actual del plan (API y panel comparten el cupo)." }, "planMonthlyLimit": { "type": [ "integer", "null" ], "description": "Cupo mensual del plan (null = sin límite)." }, "remainingThisMonth": { "type": [ "integer", "null" ] }, "decasThisPeriod": { "type": "integer" }, "remainingThisPeriod": { "type": [ "integer", "null" ] }, "periodStart": { "type": [ "string", "null" ], "description": "ISO 8601 con el desfase de Madrid, p. ej. 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 con el desfase de Madrid, p. ej. 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 = creado por la API; draft = borrador iniciado en la web." }, "origin": { "type": "string", "enum": [ "api", "web" ] }, "status": { "type": "string", "enum": [ "open", "generated", "cancelled" ] }, "version": { "type": "integer", "description": "Versión del borrador (ETag \".\")." }, "externalId": { "type": [ "string", "null" ] }, "data": { "type": "object" }, "ready": { "type": "boolean", "description": "Solo en borradores abiertos leídos uno a uno: true si se puede generar ya." }, "warnings": { "type": "array", "items": { "type": "string" } }, "issues": { "type": "array", "description": "Lo que falta o no es válido (vacío si ready es true).", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } }, "createdBy": { "type": [ "string", "null" ], "description": "Solo borradores web." }, "updatedBy": { "type": [ "string", "null" ], "description": "Solo borradores web." }, "decaId": { "type": [ "string", "null" ] }, "generatedAt": { "type": [ "string", "null" ], "description": "ISO 8601 con el desfase de Madrid, p. ej. 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 con el desfase de Madrid, p. ej. 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 con el desfase de Madrid, p. ej. 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 con el desfase de Madrid, p. ej. 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": "Aviso enviado a tu endpoint. Cabeceras: DeCA-Event-Id, DeCA-Event-Type, DeCA-Signature (t=,v1=.\">).", "properties": { "id": { "type": "string", "description": "Igual en todos los reintentos: úsalo para descartar duplicados." }, "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 con el desfase de Madrid, p. ej. 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": "Borrador con su solicitud a un tercero (estado, destinatario, caducidad)." }, "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": "Un dato habitual: id, externalId (null si se creó en la web), createdAt y los campos del recurso (los de su *Input; los envíos devuelven loadPlace y unloadPlace con id, externalId y name).", "properties": { "id": { "type": "string" }, "externalId": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "description": "ISO 8601 con el desfase de Madrid, p. ej. 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 con el desfase de Madrid, p. ej. 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 con el desfase de Madrid, p. ej. 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": "Código estable del error." }, "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "responses": { "Error": { "description": "Error. Códigos posibles:\n\n- **400** `invalid_json, idempotency_key_required, invalid_query`: Petición mal formada, falta la Idempotency-Key o un filtro no es válido.\n- **401** `invalid_credentials, credential_revoked, credential_expired`: Clave desconocida o incorrecta (misma respuesta en ambos casos), revocada o caducada.\n- **402** `business_plan_required, plan_allowance_exhausted`: El plan de la empresa no incluye la API, o se ha agotado el cupo de DeCA del plan.\n- **403** `api_addon_required, api_advanced_required, professional_plan_required, company_inactive, ip_not_allowed, insufficient_scope, sandbox_not_supported`: El complemento API no está activo, la cuenta no está activa, IP no autorizada, permiso insuficiente o endpoint no disponible con una clave de pruebas.\n- **429** `api_lite_limit_reached`: API Lite: ya se han creado por API los 100 DeCA del mes (dentro del cupo del plan). Se renueva con el periodo del plan; para más, API Advanced.\n- **404** `not_found`: No existe o no es visible para esta credencial (nunca se distingue).\n- **409** `duplicate_external_id, idempotency_conflict, deca_annulled, version_conflict, batch_without_documents, saved_in_use, company_inactive`: externalId ya usado por un DeCA activo (incluye existingId), clave de idempotencia reutilizada con otro cuerpo, DeCA anulado, corrección simultánea o lote que aún no ha creado ningún DeCA, lugar habitual usado por un envío habitual, o la empresa no tiene un Administrador al sincronizar datos habituales.\n- **402 / 403 / 409 / 422** `load_order_plan_required, load_order_not_shipper, load_order_company_nif_missing, load_order_invalid, load_order_passenger`: Orden de carga con POST /decas (loadOrder): el plan no incluye la orden de carga (402), tu empresa no es el cargador contractual (403), falta el NIF de tu empresa (409), los datos comerciales no son válidos (422, details indica el campo en /loadOrder/…) o el servicio es de viajeros (422). No se crea ningún DeCA.\n- **409** `deca_already_issued, completion_request_pending, completion_request_completed, draft_cancelled`: Solicitudes a un tercero: el DeCA ya es vigente (usa una corrección), ya hay una solicitud pendiente (usa /resend), la solicitud ya se completó, o el borrador se canceló.\n- **409** `draft_not_open, draft_limit_reached, draft_has_preparation, completion_request_no_email`: Borradores: ya generado o cancelado, límite de borradores abiertos alcanzado (incluye limit), borrador web vinculado a una solicitud a un tercero (genéralo con /api/v1/decas/{id}), o la solicitud no tiene email de destinatario.\n- **412** `precondition_failed`: If-Match no corresponde: el borrador ha cambiado desde tu última lectura. Vuelve a leerlo (cabecera ETag) y aplica tu cambio de nuevo.\n- **404** `completion_request_not_found`: Reenvío pedido para un DeCA sin ninguna solicitud a un tercero.\n- **422** `invalid_draft, invalid_completion_request, new_service_required`: El borrador o el cambio no es un objeto JSON válido (o incluye campos solo de POST /decas), la solicitud a un tercero no es válida, o la corrección cambia el servicio (crea un DeCA nuevo).\n- **413 / 415** `payload_too_large, unsupported_media_type`: Cuerpo de más de 256 KB, o no es application/json.\n- **422** `validation`: Datos no válidos. details indica cada campo con un puntero JSON y un código (required, unknown_field, invalid_country, too_short, too_long, invalid_format, invalid_value, self_company_incomplete…).\n- **422** `invalid_completion_field`: Un campo de completionRequest.fields no se puede pedir a un tercero (unknown_field) o se refiere a un envío que no existe (unknown_shipment).\n- **429** `rate_limited, daily_create_ceiling, too_many_failed_attempts`: Límite de peticiones superado. Respeta la cabecera Retry-After.\n- **500** `generation_failed, internal_error`: Error al generar (incluye correlationId y retryable: reintenta con la misma Idempotency-Key) o error interno.\n- **503** `service_unavailable, pdf_unavailable`: Servicio o PDF temporalmente no disponible: reintenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "validation", "message": "El DeCA no cumple los requisitos obligatorios.", "requestId": "req_7f3a9c…", "details": [ { "path": "/shipments/0/unloadLocation/country", "code": "invalid_country", "message": "Usa un código de país ISO 3166-1 alfa-2 (p. ej. ES, FR, PT)" } ] } } } } } } } }