{"openapi":"3.1.0","info":{"title":"API de DeCA Profesional","version":"1","description":"API REST para crear, consultar, corregir y anular DeCA desde un ERP o TMS. API Advanced: plan Business + complemento API Advanced (49,95 €/mes + IVA). API Lite (Professional) solo admite las rutas básicas: ver /developers/openapi-lite.json.\n\nAutenticación: cabecera `Authorization: Bearer <clave>`. 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"}}},"get":{"summary":"Lista los DeCA, del más reciente al más antiguo, con paginación por cursor.","description":"Filtros: limit (1–100, por defecto 25), cursor, externalId, groupageRef (referencia del grupaje, G-…), status (active | annulled), createdFrom, createdTo (DD-MM-AAAA, días en hora de Madrid; createdTo incluye todo ese día). Todas las fechas de la API van en DD-MM-AAAA y las horas en hora de Madrid.\n\nPermiso necesario: deca:read.","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Elementos por página (1–100, por defecto 25)."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"nextCursor de la página anterior."},{"name":"externalId","in":"query","required":false,"schema":{"type":"string"},"description":"Búsqueda exacta por externalId."},{"name":"groupageRef","in":"query","required":false,"schema":{"type":"string"},"description":"Referencia del grupaje (G-…); no distingue mayúsculas."},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["active","annulled"]},"description":"Estado administrativo."},{"name":"createdFrom","in":"query","required":false,"schema":{"type":"string","examples":["06-10-2026"]},"description":"Creados desde este día (DD-MM-AAAA, día en hora de Madrid; también una fecha y hora ISO 8601 con zona)."},{"name":"createdTo","in":"query","required":false,"schema":{"type":"string","examples":["06-10-2026"]},"description":"Creados hasta este día incluido (DD-MM-AAAA, día en hora de Madrid; también una fecha y hora ISO 8601 con zona)."}],"responses":{"200":{"description":"Correcto.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DecaList"}}}},"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}/versions":{"get":{"summary":"Historial de versiones: motivo del cambio, origen (api / user) y URL y PDF de cada una.","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/VersionList"}}}},"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}/vehicles":{"get":{"summary":"Vehículos del transporte: el inicial y cada cambio registrado, con el actual marcado.","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/VehicleList"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/decas/{id}/vehicle-changes":{"post":{"summary":"Registra un cambio de vehículo (tractora y, si cambia, remolque) durante el transporte.","description":"Es una corrección: nueva versión con nueva URL, QR y PDF, que no consume DeCA del plan. La fecha (DD-MM-AAAA) debe estar dentro del transporte y posterior al cambio anterior. Sin trailerPlate se mantiene el remolque anterior. Responde 201 (200 si es un reintento con la misma Idempotency-Key).\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/VehicleChange"},"example":{"tractorPlate":"5678 NPR","effectiveAt":"07-10-2026","reason":"Avería de la tractora en ruta"}}}},"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"}}}},"201":{"description":"Correcto.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Deca"}}}},"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"}}}},"/api/v1/decas/{id}/completion-request":{"post":{"summary":"Pide a un tercero, por email, los datos que faltan en un borrador.","description":"Responde 201 (200 si es un reintento con la misma Idempotency-Key). Solo borradores de la misma integración.\n\nPermiso necesario: deca:create.","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/CompletionRequest"},"example":{"recipientEmail":"operaciones@transportista.example","fields":["vehicle.tractorPlate","shipments[0].unloadLocation.city"],"expiresInHours":48}}}},"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/CompletionRequestResult"}}}},"201":{"description":"Correcto.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompletionRequestResult"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/decas/{id}/completion-request/resend":{"post":{"summary":"Reenvía la solicitud con un enlace nuevo (el anterior deja de funcionar).","description":"Responde 201 (200 si es un reintento). Máximo 5 reenvíos por borrador y hora.\n\nPermiso necesario: deca:create.","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."}],"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/CompletionRequestResult"}}}},"201":{"description":"Correcto.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompletionRequestResult"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/decas/batch":{"post":{"summary":"Crea hasta 50 DeCA en una sola llamada (lote).","description":"Cuerpo { items: [ …mismo formato que POST /decas… ] }. Responde 202 con el lote ya validado: cada elemento queda pending o failed con sus detalles (un error no afecta a los demás). La creación sigue en segundo plano; consulta GET /api/v1/batches/{id}. Cada elemento consume un DeCA del plan como una creación normal. La misma Idempotency-Key con el mismo cuerpo devuelve el mismo lote (200); nunca se duplica un DeCA.\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."}],"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/Batch"}}}},"202":{"description":"Correcto.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Batch"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/batches/{id}":{"get":{"summary":"Estado del lote y resultado de cada elemento (created, replayed, failed, pending).","description":"status pasa de processing a completed cuando todos los elementos han terminado.\n\nPermiso necesario: deca:read.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Identificador del lote."}],"responses":{"200":{"description":"Correcto.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Batch"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/batches/{id}/pdfs":{"get":{"summary":"Descarga un ZIP con el PDF vigente de cada DeCA creado por el lote.","description":"Responde 409 batch_without_documents si el lote aún no ha creado ninguno.\n\nPermiso necesario: deca:read.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Identificador del lote."}],"responses":{"200":{"description":"Correcto.","content":{"application/zip":{"schema":{"type":"string","format":"binary"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/drafts":{"post":{"summary":"Abre un borrador nuevo e independiente (datos parciales). No consume cuota.","description":"Responde 201 con draftId (200 si es un reintento con la misma Idempotency-Key).\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/DraftCreate"},"example":{"externalId":"VIAJE-4471","reference":"Pedido 88231","loadDate":"06-10-2026","unloadDate":"07-10-2026","shipper":{"name":"CERÁMICAS DEL MEDITERRÁNEO S.A.","taxId":"A12345674","country":"ES","address":"Carretera de Alcora km 3","postalCode":"12006","city":"Castellón de la Plana"},"carrier":"self"}}}},"responses":{"200":{"description":"Reintento con la misma Idempotency-Key y el mismo cuerpo: el resultado original (cabecera Idempotent-Replayed: true).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Draft"}}}},"201":{"description":"Correcto.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Draft"}}}},"default":{"$ref":"#/components/responses/Error"}}},"get":{"summary":"Lista los borradores: status=open (por defecto) | generated | cancelled | all.","description":"Paginado con limit y cursor, como /decas. Los borradores son de la empresa: con deca:read_company verás también los empezados en la web (origin: \"web\") y los de otras integraciones, y podrás completarlos, generarlos o descartarlos.\n\nPermiso necesario: deca:read.","parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["open","generated","cancelled","all"],"default":"open"},"description":"Estado de los borradores (por defecto open)."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Elementos por página (1–100, por defecto 25)."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"nextCursor de la página anterior."}],"responses":{"200":{"description":"Correcto.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DraftList"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/drafts/{id}":{"get":{"summary":"Un borrador, con ready e issues (lo que falta para poder generarlo).","description":"Permiso necesario: deca:read.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Identificador del borrador."}],"responses":{"200":{"description":"Correcto.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Draft"}}}},"default":{"$ref":"#/components/responses/Error"}}},"patch":{"summary":"Modifica o completa un borrador abierto (JSON Merge Patch).","description":"Opcional If-Match con el ETag: 412 si otro cambio llegó antes.\n\nPermiso necesario: deca:create.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Identificador del borrador."},{"name":"If-Match","in":"header","required":false,"schema":{"type":"string"},"description":"ETag leído del borrador: evita sobrescribir cambios de otro (412 precondition_failed)."}],"requestBody":{"required":true,"content":{"application/merge-patch+json":{"schema":{"$ref":"#/components/schemas/DraftPatch"},"example":{"vehicle":{"tractorPlate":"1234 KLM"},"shipments":[{"loadLocation":{"name":"Planta 1","address":"Carretera de Alcora km 3","postalCode":"12006","city":"Castellón de la Plana","country":"ES"},"unloadLocation":{"name":"Almacenes Norte","address":"Polígono Arasur, calle C 14","postalCode":"01230","city":"Ribabellosa","country":"ES"},"goods":"Azulejo cerámico en palés","weight":18400}]}}}},"responses":{"200":{"description":"Correcto.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Draft"}}}},"default":{"$ref":"#/components/responses/Error"}}},"delete":{"summary":"Descarta un borrador abierto (queda como cancelled).","description":"Permiso necesario: deca:create.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Identificador del borrador."},{"name":"If-Match","in":"header","required":false,"schema":{"type":"string"},"description":"ETag leído del borrador: evita sobrescribir cambios de otro (412 precondition_failed)."}],"responses":{"200":{"description":"Correcto.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Draft"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/drafts/{id}/generate":{"post":{"summary":"Genera el DeCA definitivo de ese borrador; los demás no cambian.","description":"201 con el DeCA; repetir devuelve el mismo DeCA (200). Aquí se consume la cuota.\n\nPermiso necesario: deca:create.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Identificador del borrador."},{"name":"If-Match","in":"header","required":false,"schema":{"type":"string"},"description":"ETag leído del borrador: evita sobrescribir cambios de otro (412 precondition_failed)."}],"responses":{"201":{"description":"Correcto.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Deca"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/decas/{id}/service-completion":{"post":{"summary":"Marca el servicio como finalizado (dato operativo; el DeCA, su PDF y su URL no cambian).","description":"Cuerpo opcional { note } (hasta 500 caracteres). Idempotente: devuelve el DeCA con service.finished. 409 deca_annulled en un DeCA anulado. Webhook deca.service_finished.\n\nPermiso necesario: deca:correct.","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"}}},"delete":{"summary":"Reabre un servicio marcado como finalizado (vuelve a pendiente).","description":"Idempotente. Webhook deca.service_reopened.\n\nPermiso necesario: deca:correct.","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/load-orders":{"get":{"summary":"Lista las órdenes de carga: número, estado, formato (junta o separada), DeCA vinculado, matrículas pendientes y aceptación.","description":"Filtros: decaId, status (pending_vehicle | active | cancelled), limit (1–100). Sin deca:read_company, solo las de DeCA creados por tu integración. Nunca incluye el precio ni las condiciones (están en el PDF). Para emitirla: POST /api/v1/decas con loadOrder.\n\nPermiso necesario: deca:read.","parameters":[{"name":"decaId","in":"query","required":false,"schema":{"type":"string"},"description":"Solo la orden de este DeCA."},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["pending_vehicle","active","cancelled"]},"description":"Estado de la orden de carga."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Número máximo de órdenes (1–100, por defecto 50)."}],"responses":{"200":{"description":"Correcto.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoadOrderList"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/load-orders/{id}":{"get":{"summary":"Una orden de carga: estado, versión vigente, DeCA vinculado y aceptación del transportista.","description":"Permiso necesario: deca:read.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Identificador de la orden de carga."}],"responses":{"200":{"description":"Correcto.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoadOrder"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/load-orders/{id}/pdf":{"get":{"summary":"El PDF de la versión vigente de la orden de carga.","description":"Permiso necesario: deca:read.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Identificador de la orden de carga."}],"responses":{"200":{"description":"Correcto.","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/saved/companies":{"get":{"summary":"Lista las empresas habituales (cargadores y transportistas) de la empresa.","description":"Orden de creación. Parámetros: limit (1–100, por defecto 50), cursor (nextCursor de la página anterior) y externalId (búsqueda exacta). Incluye también los registros creados en la web (externalId null).\n\nPermiso necesario: saved:read.","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100},"description":"Elementos por página (por defecto 50)."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"nextCursor de la página anterior."},{"name":"externalId","in":"query","required":false,"schema":{"type":"string"},"description":"Búsqueda exacta por externalId."}],"responses":{"200":{"description":"Correcto.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavedList"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/saved/companies/{externalId}":{"get":{"summary":"Lee un registro por el identificador de tu ERP o TMS (externalId).","description":"Permiso necesario: saved:read.","parameters":[{"name":"externalId","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9._~:-]{1,100}$"},"description":"El identificador del registro en tu ERP o TMS."}],"responses":{"200":{"description":"Correcto.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavedRecord"}}}},"default":{"$ref":"#/components/responses/Error"}}},"put":{"summary":"Crea o actualiza el registro con ese externalId (sincronización sin duplicados).","description":"Responde 201 si lo crea y 200 si lo actualiza; repetir la misma llamada deja el mismo registro. Se valida con las mismas reglas que la web y aparece al momento en Datos habituales. Nunca cambia un DeCA ya generado.\n\nPermiso necesario: saved:write.","parameters":[{"name":"externalId","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9._~:-]{1,100}$"},"description":"El identificador del registro en tu ERP o TMS."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavedCompanyInput"},"example":{"name":"Cerámicas del Mediterráneo S.A.","taxId":"A12345674","address":"Carretera de Alcora km 3","postalCode":"12006","city":"Castellón de la Plana","role":"shipper"}}}},"responses":{"200":{"description":"Correcto.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavedRecord"}}}},"201":{"description":"Creado (no existía ningún registro con ese externalId).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavedRecord"}}}},"default":{"$ref":"#/components/responses/Error"}}},"delete":{"summary":"Borra el registro con ese externalId.","description":"Nunca cambia un DeCA ya generado.\n\nPermiso necesario: saved:write.","parameters":[{"name":"externalId","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9._~:-]{1,100}$"},"description":"El identificador del registro en tu ERP o TMS."}],"responses":{"200":{"description":"Correcto.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavedDeleted"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/saved/vehicles":{"get":{"summary":"Lista los vehículos habituales (con su conductor habitual) de la empresa.","description":"Orden de creación. Parámetros: limit (1–100, por defecto 50), cursor (nextCursor de la página anterior) y externalId (búsqueda exacta). Incluye también los registros creados en la web (externalId null).\n\nPermiso necesario: saved:read.","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100},"description":"Elementos por página (por defecto 50)."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"nextCursor de la página anterior."},{"name":"externalId","in":"query","required":false,"schema":{"type":"string"},"description":"Búsqueda exacta por externalId."}],"responses":{"200":{"description":"Correcto.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavedList"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/saved/vehicles/{externalId}":{"get":{"summary":"Lee un registro por el identificador de tu ERP o TMS (externalId).","description":"Permiso necesario: saved:read.","parameters":[{"name":"externalId","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9._~:-]{1,100}$"},"description":"El identificador del registro en tu ERP o TMS."}],"responses":{"200":{"description":"Correcto.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavedRecord"}}}},"default":{"$ref":"#/components/responses/Error"}}},"put":{"summary":"Crea o actualiza el registro con ese externalId (sincronización sin duplicados).","description":"Responde 201 si lo crea y 200 si lo actualiza; repetir la misma llamada deja el mismo registro. Se valida con las mismas reglas que la web y aparece al momento en Datos habituales. Nunca cambia un DeCA ya generado.\n\nPermiso necesario: saved:write.","parameters":[{"name":"externalId","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9._~:-]{1,100}$"},"description":"El identificador del registro en tu ERP o TMS."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavedVehicleInput"},"example":{"tractorPlate":"1234 KLM","trailerPlate":"R-5678-BCD","alias":"Camión 12","habitualDriver":{"name":"Luis Pérez","phone":"+34 600 111 222","email":"luis@transportes.example"}}}}},"responses":{"200":{"description":"Correcto.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavedRecord"}}}},"201":{"description":"Creado (no existía ningún registro con ese externalId).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavedRecord"}}}},"default":{"$ref":"#/components/responses/Error"}}},"delete":{"summary":"Borra el registro con ese externalId.","description":"Nunca cambia un DeCA ya generado.\n\nPermiso necesario: saved:write.","parameters":[{"name":"externalId","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9._~:-]{1,100}$"},"description":"El identificador del registro en tu ERP o TMS."}],"responses":{"200":{"description":"Correcto.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavedDeleted"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/saved/places":{"get":{"summary":"Lista los lugares habituales de carga y descarga de la empresa.","description":"Orden de creación. Parámetros: limit (1–100, por defecto 50), cursor (nextCursor de la página anterior) y externalId (búsqueda exacta). Incluye también los registros creados en la web (externalId null).\n\nPermiso necesario: saved:read.","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100},"description":"Elementos por página (por defecto 50)."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"nextCursor de la página anterior."},{"name":"externalId","in":"query","required":false,"schema":{"type":"string"},"description":"Búsqueda exacta por externalId."}],"responses":{"200":{"description":"Correcto.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavedList"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/saved/places/{externalId}":{"get":{"summary":"Lee un registro por el identificador de tu ERP o TMS (externalId).","description":"Permiso necesario: saved:read.","parameters":[{"name":"externalId","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9._~:-]{1,100}$"},"description":"El identificador del registro en tu ERP o TMS."}],"responses":{"200":{"description":"Correcto.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavedRecord"}}}},"default":{"$ref":"#/components/responses/Error"}}},"put":{"summary":"Crea o actualiza el registro con ese externalId (sincronización sin duplicados).","description":"Responde 201 si lo crea y 200 si lo actualiza; repetir la misma llamada deja el mismo registro. Se valida con las mismas reglas que la web y aparece al momento en Datos habituales. Nunca cambia un DeCA ya generado.\n\nPermiso necesario: saved:write.","parameters":[{"name":"externalId","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9._~:-]{1,100}$"},"description":"El identificador del registro en tu ERP o TMS."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavedPlaceInput"},"example":{"name":"Almacén Norte","address":"Polígono Arasur, calle C 14","postalCode":"01230","city":"Ribabellosa","province":"Álava","type":"unload"}}}},"responses":{"200":{"description":"Correcto.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavedRecord"}}}},"201":{"description":"Creado (no existía ningún registro con ese externalId).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavedRecord"}}}},"default":{"$ref":"#/components/responses/Error"}}},"delete":{"summary":"Borra el registro con ese externalId.","description":"Responde 409 saved_in_use si un envío habitual usa ese lugar.\n\nPermiso necesario: saved:write.","parameters":[{"name":"externalId","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9._~:-]{1,100}$"},"description":"El identificador del registro en tu ERP o TMS."}],"responses":{"200":{"description":"Correcto.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavedDeleted"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/saved/shipments":{"get":{"summary":"Lista los envíos habituales (lugar de carga + lugar de descarga + mercancía) de la empresa.","description":"Orden de creación. Parámetros: limit (1–100, por defecto 50), cursor (nextCursor de la página anterior) y externalId (búsqueda exacta). Incluye también los registros creados en la web (externalId null).\n\nPermiso necesario: saved:read.","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100},"description":"Elementos por página (por defecto 50)."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"nextCursor de la página anterior."},{"name":"externalId","in":"query","required":false,"schema":{"type":"string"},"description":"Búsqueda exacta por externalId."}],"responses":{"200":{"description":"Correcto.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavedList"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/saved/shipments/{externalId}":{"get":{"summary":"Lee un registro por el identificador de tu ERP o TMS (externalId).","description":"Permiso necesario: saved:read.","parameters":[{"name":"externalId","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9._~:-]{1,100}$"},"description":"El identificador del registro en tu ERP o TMS."}],"responses":{"200":{"description":"Correcto.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavedRecord"}}}},"default":{"$ref":"#/components/responses/Error"}}},"put":{"summary":"Crea o actualiza el registro con ese externalId (sincronización sin duplicados).","description":"Responde 201 si lo crea y 200 si lo actualiza; repetir la misma llamada deja el mismo registro. Se valida con las mismas reglas que la web y aparece al momento en Datos habituales. Los lugares se indican con su externalId (loadPlaceExternalId, unloadPlaceExternalId): sincronízalos antes. Nunca cambia un DeCA ya generado.\n\nPermiso necesario: saved:write.","parameters":[{"name":"externalId","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9._~:-]{1,100}$"},"description":"El identificador del registro en tu ERP o TMS."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavedShipmentInput"},"example":{"name":"Castellón → Arasur","loadPlaceExternalId":"ALM-CS","unloadPlaceExternalId":"ALM-NORTE","goods":"Azulejo cerámico en palés","weight":"18.400 kg"}}}},"responses":{"200":{"description":"Correcto.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavedRecord"}}}},"201":{"description":"Creado (no existía ningún registro con ese externalId).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavedRecord"}}}},"default":{"$ref":"#/components/responses/Error"}}},"delete":{"summary":"Borra el registro con ese externalId.","description":"Nunca cambia un DeCA ya generado.\n\nPermiso necesario: saved:write.","parameters":[{"name":"externalId","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9._~:-]{1,100}$"},"description":"El identificador del registro en tu ERP o TMS."}],"responses":{"200":{"description":"Correcto.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavedDeleted"}}}},"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 \"<id>.<version>\")."},"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=<s>,v1=<HMAC-SHA256 hex de \"<t>.<cuerpo>\">).","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)"}]}}}}}}}}