{"openapi":"3.1.0","info":{"title":"API DECA \u00b7 decasimple","version":"1.0.0","description":"Crea y consulta documentos DECA desde cualquier lenguaje mediante un contrato HTTP p\u00fablico con nombres camelCase y objetos por entidad.\n\nLos ejemplos HTTP de la referencia incluyen cURL, JavaScript (fetch), PHP (extensi\u00f3n cURL), Python (urllib.request, biblioteca est\u00e1ndar), C# (HttpClient de .NET) y Java (HttpClient, Java 11 o posterior). La selecci\u00f3n de lenguaje se aplica a toda la p\u00e1gina. Son ejemplos peque\u00f1os para usar desde consola, aplicaciones de escritorio o servicios, sin depender de un framework.\n\nLos IDs de empresas y documentos son UUID v4 p\u00fablicos y estables. Obt\u00e9n el id de la empresa mediante GET \/companies y \u00fasalo como {company} en las rutas; companyId contiene ese mismo UUID. En producci\u00f3n, id identifica el documento guardado; en sandbox es null porque no se guarda. Las rutas con un ID num\u00e9rico devuelven 404. Cada operaci\u00f3n sigue comprobando el acceso del token a la empresa. Las nuevas referencias de producci\u00f3n usan DECA-ULID y se mantienen al completar el borrador o emitir revisiones. Las referencias hist\u00f3ricas siguen siendo v\u00e1lidas para consultar y filtrar documentos.\n\nEl cuerpo JSON admite informaci\u00f3n parcial: si faltan requisitos de emisi\u00f3n, HTTP 201 devuelve status=draft y pendingFields; no se genera PDF. Si los datos est\u00e1n completos y son v\u00e1lidos, HTTP 201 devuelve status=issued. Los valores enviados inv\u00e1lidos o los campos desconocidos devuelven HTTP 422.\n\n**Empieza en sandbox.** No guarda documentos, revisiones, contactos ni veh\u00edculos, requiere Pro activo y no consume l\u00edmites documentales. Un sandbox completo devuelve un PDF de prueba marcado PRUEBA \u00b7 SIN VALIDEZ en base64, con url=null. Un sandbox incompleto no devuelve ni genera PDF. **Producci\u00f3n guarda un documento nuevo por POST** como borrador o emitido y requiere Pro activo. Los emitidos devuelven una URL p\u00fablica directa al PDF y sus metadatos, sin base64. Ning\u00fan entorno crea contactos\/veh\u00edculos ni env\u00eda correos al transportista.\n\nCrea un token en **API e integraciones** del panel, indicando entorno y caducidad (1\u2013365 d\u00edas). El secreto solo se muestra una vez. El propietario accede a todas las empresas de su cuenta; los colaboradores requieren acceso a la empresa y permiso expl\u00edcito para API. Usa un token del mismo entorno que la ruta. No se usan cookies, sesi\u00f3n ni CSRF. Guarda los tokens de producci\u00f3n en tu servidor.\n\nLas consultas y creaciones comparten **30 peticiones\/minuto por cuenta y entorno**, entre todos sus tokens; adem\u00e1s hay **120 peticiones\/minuto por IP**.\n\n**Idempotencia opcional en producci\u00f3n.** Env\u00eda un UUID en el encabezado Idempotency-Key y reutil\u00edzalo al reintentar la misma operaci\u00f3n: devuelve el documento existente sin otra emisi\u00f3n. Sin este encabezado, repetir POST crea otro documento; customerReference no deduplica. Ante un resultado incierto sin clave, comprueba el panel antes de repetir. Puedes consultar los documentos de una empresa con filtros exactos y paginaci\u00f3n, por defecto en los \u00faltimos 30 d\u00edas naturales de creaci\u00f3n en UTC. Se admiten periodos hist\u00f3ricos de hasta 30 d\u00edas inclusivos. La lectura requiere Pro activo en la empresa; sandbox devuelve una lista vac\u00eda. La API v1 no actualiza documentos existentes: completa los borradores desde el panel.\n\nLa respuesta es JSON o XML seg\u00fan Accept; ?format=json o ?format=xml tiene prioridad. Sin Accept se devuelve JSON. Los errores usan rutas de campos del contrato p\u00fablico. El contrato usa nombres p\u00fablicos: no se admiten nombres internos en snake_case.","contact":{"email":"soporte@decasimple.com"}},"servers":[{"url":"\/api\/v1\/sandbox","description":"Sandbox \u00b7 borradores y emisi\u00f3n de prueba sin persistencia"},{"url":"\/api\/v1\/production","description":"Producci\u00f3n \u00b7 crea un borrador o emite un DECA real"}],"security":[{"BearerAuth":[]}],"tags":[{"name":"Empresas","description":"Empresas habilitadas para el usuario y la cuenta del token."},{"name":"Documentos","description":"Consulta de documentos archivados y creaci\u00f3n de borradores o emisi\u00f3n DECA."}],"paths":{"\/companies":{"get":{"tags":["Empresas"],"summary":"Listar empresas disponibles","operationId":"listCompanies","description":"Devuelve las empresas accesibles del token con id (UUID v4 p\u00fablico y estable), name y taxId. Usa uno de estos UUID en {company} para consultar o crear documentos. La lista incorpora empresas futuras de la cuenta para el propietario; los colaboradores requieren permiso expl\u00edcito.","parameters":[{"$ref":"#\/components\/parameters\/ResponseFormat"}],"responses":{"200":{"description":"Empresas disponibles para la cuenta y el entorno del token.","headers":{"X-RateLimit-Limit":{"$ref":"#\/components\/headers\/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#\/components\/headers\/RateLimitRemaining"}},"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/CompanyListResponse"},"example":{"data":[{"id":"2f940ade-912c-4a85-a2b5-eec8a9ae4342","name":"Empresa API","taxId":"B12345674"}],"environment":"sandbox"}},"application\/xml":{"schema":{"type":"string"},"example":"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response><data><item key=\"0\"><id>2f940ade-912c-4a85-a2b5-eec8a9ae4342<\/id><name>Empresa API<\/name><taxId>B12345674<\/taxId><\/item><\/data><environment>sandbox<\/environment><\/response>\n"}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"406":{"$ref":"#\/components\/responses\/NotAcceptable"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"},"500":{"$ref":"#\/components\/responses\/InternalServerError"}}}},"\/companies\/{company}\/decas":{"get":{"tags":["Documentos"],"summary":"Listar documentos de una empresa","operationId":"listDecas","description":"Consulta los documentos guardados en la empresa, tanto desde el panel como desde la API de producci\u00f3n. La lectura requiere Pro activo en la empresa. El archivo sigue accesible en el panel al bajar a Gratis. La consulta no genera ni lee PDF; solo devuelve datos, enlaces y metadatos. En sandbox, tras validar permisos y par\u00e1metros, siempre devuelve data=[] y total=0, sin mostrar documentos reales.\n\n**Periodo por creaci\u00f3n en UTC:** sin from ni to se aplican hoy menos 29 d\u00edas y hoy, ambos incluidos. Si solo indicas to, from=to\u221229 d\u00edas. Si solo indicas from, to es la fecha menor entre from+29 d\u00edas y hoy. Puedes consultar periodos hist\u00f3ricos de hasta **30 d\u00edas naturales inclusivos**: from y to no pueden ser futuros, from debe ser anterior o igual a to y la diferencia entre ambas fechas no puede superar 29 d\u00edas. No es un filtro por transportDate ni updatedAt. Las fechas van en YYYY-MM-DD.\n\nLos filtros status, reference, customerReference y transportDate son opcionales y de coincidencia exacta; se combinan con el periodo de creaci\u00f3n. transportDate puede ser pasada o futura. page empieza en 1; perPage vale 20 por defecto y admite de 1 a 100. Se rechazan los par\u00e1metros desconocidos con 422, salvo el par\u00e1metro de respuesta format. El orden es createdAt descendente, con orden estable en los empates.\n\nEl resultado incluye environment, data y meta, sin enlaces de paginaci\u00f3n. Cada elemento contiene createdAt y updatedAt. Los borradores incluyen document parcial y pendingFields con datos faltantes o inv\u00e1lidos, sin pdf ni url. Los emitidos incluyen los datos y metadatos de la \u00faltima versi\u00f3n, que puede superar 1, y una URL p\u00fablica directa al PDF, sin contenido binario. meta.period muestra las fechas aplicadas y timeZone=UTC.","parameters":[{"name":"company","in":"path","required":true,"description":"UUID v4 p\u00fablico y estable de empresa obtenido mediante GET \/companies. Un ID num\u00e9rico devuelve 404. Se comprueba el acceso del token a esta empresa en cada operaci\u00f3n.","schema":{"type":"string","format":"uuid"},"example":"2f940ade-912c-4a85-a2b5-eec8a9ae4342"},{"name":"from","in":"query","required":false,"description":"Primer d\u00eda de creaci\u00f3n incluido, YYYY-MM-DD, en UTC. No puede ser futuro ni posterior a to. Sin fechas: hoy menos 29 d\u00edas. Si solo se indica to: to menos 29 d\u00edas.","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","required":false,"description":"\u00daltimo d\u00eda de creaci\u00f3n incluido, YYYY-MM-DD, en UTC. No puede ser futuro. El periodo from\u2013to admite como m\u00e1ximo 30 d\u00edas naturales inclusivos. Si solo se indica from: la fecha menor entre from + 29 d\u00edas y hoy.","schema":{"type":"string","format":"date"}},{"name":"status","in":"query","required":false,"description":"Estado exacto del documento. Omitido devuelve borradores y emitidos.","schema":{"type":"string","enum":["draft","issued"]}},{"name":"reference","in":"query","required":false,"description":"Referencia DECA exacta asignada al documento.","schema":{"type":"string","maxLength":40}},{"name":"customerReference","in":"query","required":false,"description":"Referencia de cliente exacta. Puede coincidir con varios documentos; no es una clave de idempotencia.","schema":{"type":"string","maxLength":100}},{"name":"transportDate","in":"query","required":false,"description":"Fecha de transporte exacta, YYYY-MM-DD. Admite fechas pasadas o futuras; se combina con el periodo de creaci\u00f3n from\u2013to.","schema":{"type":"string","format":"date"}},{"name":"page","in":"query","required":false,"description":"P\u00e1gina solicitada, empezando en 1. Una p\u00e1gina sin resultados devuelve data vac\u00edo.","schema":{"type":"integer","minimum":1,"default":1}},{"name":"perPage","in":"query","required":false,"description":"Documentos por p\u00e1gina. Por defecto 20; entre 1 y 100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"$ref":"#\/components\/parameters\/ResponseFormat"}],"responses":{"200":{"description":"P\u00e1gina de documentos de la empresa. La lista puede estar vac\u00eda por filtros o n\u00famero de p\u00e1gina. Sandbox siempre devuelve una lista vac\u00eda, total=0 y lastPage=1, conservando la p\u00e1gina y el tama\u00f1o solicitados.","headers":{"X-RateLimit-Limit":{"$ref":"#\/components\/headers\/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#\/components\/headers\/RateLimitRemaining"}},"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/DecaListResponse"},"examples":{"production":{"summary":"Producci\u00f3n: \u00faltima versi\u00f3n y borrador parcial","value":{"environment":"production","data":[{"id":"7f84ca0e-fd39-454f-926c-338f19ac8c61","companyId":"2f940ade-912c-4a85-a2b5-eec8a9ae4342","reference":"DECA-01ARZ3NDEKTSV4RRFFQ69G5FAV","status":"issued","version":2,"document":{"companyRole":"shipper","customerReference":"PED-1042","transportDate":"2026-10-15","carrier":{"name":"Transportes de ejemplo","taxId":"B87654323","address":"Calle Industria 8, Sevilla"},"vehicle":{"plate":"1234 ABC","articulated":false,"trailerPlate":null},"specialTransport":{"enabled":false,"authorization":null},"deliveries":[{"recipientName":"Almac\u00e9n de ejemplo","originAddress":"Calle Comercio 1, Sevilla","destinationAddress":"Calle Mayor 2, Madrid","goods":"Material embalado","weightKg":2400.5,"packages":12,"weightDescription":null,"unloadingDate":null}],"shipper":{"name":"Empresa API","taxId":"B12345674","address":"Calle Mayor 12, Madrid, Espa\u00f1a"}},"url":"https:\/\/deca.example\/deca\/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.pdf","pdf":{"fileName":"DECA-01ARZ3NDEKTSV4RRFFQ69G5FAV-v2.pdf","contentType":"application\/pdf","sha256":"e5c62df5dab5c87b6a015ef3d43597074d1eec433b15f51aec63b8582d0e4ab4"},"createdAt":"2026-10-08T08:30:00Z","updatedAt":"2026-10-08T10:15:00Z"},{"id":"0f359e06-57f9-4827-afef-eab01a33255e","companyId":"2f940ade-912c-4a85-a2b5-eec8a9ae4342","reference":"DECA-01ARZ3NDEKTSV4RRFFQ69G5FAW","status":"draft","version":0,"pendingFields":["carrier.taxId","vehicle.plate","deliveries.0.destinationAddress","deliveries.0.goods","deliveries.0.weightKg"],"createdAt":"2026-10-07T14:00:00Z","updatedAt":"2026-10-07T14:00:00Z","document":{"customerReference":"PED-PENDIENTE","transportDate":"2026-10-15","carrier":{"name":"Transportes de ejemplo"},"deliveries":[{"originAddress":"Calle Comercio 1, Sevilla"}],"companyRole":"shipper","shipper":{"name":"Empresa API","taxId":"B12345674","address":"Calle Mayor 12, Madrid, Espa\u00f1a"},"vehicle":{"articulated":false},"specialTransport":{"enabled":false}}}],"meta":{"currentPage":1,"perPage":20,"total":2,"lastPage":1,"period":{"from":"2026-09-09","to":"2026-10-08","timeZone":"UTC"}}}},"sandbox":{"summary":"Sandbox: lista vac\u00eda","value":{"environment":"sandbox","data":[],"meta":{"currentPage":1,"perPage":20,"total":0,"lastPage":1,"period":{"from":"2026-09-09","to":"2026-10-08","timeZone":"UTC"}}}}}},"application\/xml":{"schema":{"type":"string","description":"XML con ra\u00edz response, listas item key=\"0\" y nulos null=\"true\"."},"examples":{"production":{"summary":"Producci\u00f3n: \u00faltima versi\u00f3n y borrador parcial","value":"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response><environment>production<\/environment><data><item key=\"0\"><id>7f84ca0e-fd39-454f-926c-338f19ac8c61<\/id><companyId>2f940ade-912c-4a85-a2b5-eec8a9ae4342<\/companyId><reference>DECA-01ARZ3NDEKTSV4RRFFQ69G5FAV<\/reference><status>issued<\/status><version>2<\/version><document><companyRole>shipper<\/companyRole><customerReference>PED-1042<\/customerReference><transportDate>2026-10-15<\/transportDate><carrier><name>Transportes de ejemplo<\/name><taxId>B87654323<\/taxId><address>Calle Industria 8, Sevilla<\/address><\/carrier><vehicle><plate>1234 ABC<\/plate><articulated>false<\/articulated><trailerPlate null=\"true\"\/><\/vehicle><specialTransport><enabled>false<\/enabled><authorization null=\"true\"\/><\/specialTransport><deliveries><item key=\"0\"><recipientName>Almac\u00e9n de ejemplo<\/recipientName><originAddress>Calle Comercio 1, Sevilla<\/originAddress><destinationAddress>Calle Mayor 2, Madrid<\/destinationAddress><goods>Material embalado<\/goods><weightKg>2400.5<\/weightKg><packages>12<\/packages><weightDescription null=\"true\"\/><unloadingDate null=\"true\"\/><\/item><\/deliveries><shipper><name>Empresa API<\/name><taxId>B12345674<\/taxId><address>Calle Mayor 12, Madrid, Espa\u00f1a<\/address><\/shipper><\/document><url>https:\/\/deca.example\/deca\/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.pdf<\/url><pdf><fileName>DECA-01ARZ3NDEKTSV4RRFFQ69G5FAV-v2.pdf<\/fileName><contentType>application\/pdf<\/contentType><sha256>e5c62df5dab5c87b6a015ef3d43597074d1eec433b15f51aec63b8582d0e4ab4<\/sha256><\/pdf><createdAt>2026-10-08T08:30:00Z<\/createdAt><updatedAt>2026-10-08T10:15:00Z<\/updatedAt><\/item><item key=\"1\"><id>0f359e06-57f9-4827-afef-eab01a33255e<\/id><companyId>2f940ade-912c-4a85-a2b5-eec8a9ae4342<\/companyId><reference>DECA-01ARZ3NDEKTSV4RRFFQ69G5FAW<\/reference><status>draft<\/status><version>0<\/version><pendingFields><item key=\"0\">carrier.taxId<\/item><item key=\"1\">vehicle.plate<\/item><item key=\"2\">deliveries.0.destinationAddress<\/item><item key=\"3\">deliveries.0.goods<\/item><item key=\"4\">deliveries.0.weightKg<\/item><\/pendingFields><createdAt>2026-10-07T14:00:00Z<\/createdAt><updatedAt>2026-10-07T14:00:00Z<\/updatedAt><document><customerReference>PED-PENDIENTE<\/customerReference><transportDate>2026-10-15<\/transportDate><carrier><name>Transportes de ejemplo<\/name><\/carrier><deliveries><item key=\"0\"><originAddress>Calle Comercio 1, Sevilla<\/originAddress><\/item><\/deliveries><companyRole>shipper<\/companyRole><shipper><name>Empresa API<\/name><taxId>B12345674<\/taxId><address>Calle Mayor 12, Madrid, Espa\u00f1a<\/address><\/shipper><vehicle><articulated>false<\/articulated><\/vehicle><specialTransport><enabled>false<\/enabled><\/specialTransport><\/document><\/item><\/data><meta><currentPage>1<\/currentPage><perPage>20<\/perPage><total>2<\/total><lastPage>1<\/lastPage><period><from>2026-09-09<\/from><to>2026-10-08<\/to><timeZone>UTC<\/timeZone><\/period><\/meta><\/response>\n"},"sandbox":{"summary":"Sandbox: lista vac\u00eda","value":"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response><environment>sandbox<\/environment><data><\/data><meta><currentPage>1<\/currentPage><perPage>20<\/perPage><total>0<\/total><lastPage>1<\/lastPage><period><from>2026-09-09<\/from><to>2026-10-08<\/to><timeZone>UTC<\/timeZone><\/period><\/meta><\/response>\n"}}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"description":"Token de otro entorno o ninguna empresa habilitada para la API. Una empresa sin Pro no puede usar la API; conserva la consulta y descarga desde el panel.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ErrorResponse"},"example":{"error":{"status":403,"message":"El token no corresponde a este entorno.","details":[]}}},"application\/xml":{"schema":{"type":"string","description":"XML con ra\u00edz response; las listas usan item con atributo key y los nulos, null=\"true\"."},"example":"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response><error><status>403<\/status><message>El token no corresponde a este entorno.<\/message><details><\/details><\/error><\/response>\n"}}},"404":{"$ref":"#\/components\/responses\/NotFound"},"406":{"$ref":"#\/components\/responses\/NotAcceptable"},"422":{"description":"Par\u00e1metros de consulta inv\u00e1lidos o desconocidos: fechas de creaci\u00f3n futuras, periodo invertido o superior a 30 d\u00edas inclusivos, estado no admitido, referencias demasiado largas o paginaci\u00f3n fuera de rango. error.details utiliza los nombres p\u00fablicos de los par\u00e1metros.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ErrorResponse"},"example":{"error":{"status":422,"message":"Hay par\u00e1metros que necesitan corregirse.","details":{"to":["El periodo no puede superar 30 d\u00edas naturales inclusivos."]}}}},"application\/xml":{"schema":{"type":"string"},"example":"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response><error><status>422<\/status><message>Hay par\u00e1metros que necesitan corregirse.<\/message><details><to><item key=\"0\">El periodo no puede superar 30 d\u00edas naturales inclusivos.<\/item><\/to><\/details><\/error><\/response>\n"}}},"429":{"$ref":"#\/components\/responses\/TooManyRequests"},"500":{"$ref":"#\/components\/responses\/InternalServerError"}}},"post":{"tags":["Documentos"],"summary":"Crear un DECA: borrador o emitido","operationId":"createDeca","description":"Env\u00eda un **objeto JSON** con campos p\u00fablicos camelCase, agrupados en shipper, carrier, vehicle, specialTransport y deliveries. No uses una envolvente data ni nombres internos en snake_case. Solo se toma el cuerpo; la query no completa campos del documento. El tama\u00f1o m\u00e1ximo es **256 KiB**. Todos los campos desconocidos se rechazan con HTTP 422.\n\ncompanyRole indica el papel de tu empresa: shipper por defecto o carrier. La identidad de ese papel se obtiene siempre de la empresa elegida, sustituyendo los valores enviados. Proporciona la contraparte. vehicle.articulated y specialTransport.enabled valen false cuando se omiten; null no es v\u00e1lido para esos booleanos.\n\nSi faltan requisitos de emisi\u00f3n, se devuelve **201, status=draft, version=0 y pendingFields**. No se genera PDF, revisi\u00f3n ni enlace, y se omiten document, pdf y url. En producci\u00f3n se guarda el borrador para completarlo desde el panel; en sandbox no se guarda. Un dato no vac\u00edo inv\u00e1lido (NIF, matr\u00edcula, fecha, tipo, rango o longitud) devuelve 422, no se convierte en un borrador.\n\nCon todos los requisitos v\u00e1lidos, se devuelve **201, status=issued, version=1**. En producci\u00f3n, data.url permite acceder y descargar directamente el PDF sin Bearer; data.pdf solo contiene fileName, contentType y sha256. No decodifiques la respuesta de producci\u00f3n: descarga el archivo desde la URL y comprueba SHA-256 sobre sus bytes. En sandbox, id y url son null, y pdf incluye encoding=base64 y content con un PDF marcado de prueba.\n\n**Idempotency-Key opcional:** un UUID estable identifica la operaci\u00f3n en esta empresa. Reutilizarlo devuelve el documento existente sin otra emisi\u00f3n. Sin clave, cada POST de producci\u00f3n crea un documento nuevo, incluso si repites customerReference. Revocar el token de API no revoca el enlace p\u00fablico del PDF.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"UUID estable de esta operaci\u00f3n de producci\u00f3n. Reutil\u00edzalo al reintentar para devolver el documento existente sin consumir otra emisi\u00f3n. Sin encabezado, cada POST crea otro documento. No identifica operaciones del entorno de pruebas.","schema":{"type":"string","format":"uuid"},"example":"74bc9f3a-217a-4fdb-a526-8f6a98627086"},{"name":"company","in":"path","required":true,"description":"UUID v4 p\u00fablico y estable de empresa obtenido mediante GET \/companies. Un ID num\u00e9rico devuelve 404. Se comprueba el acceso del token a esta empresa en cada operaci\u00f3n.","schema":{"type":"string","format":"uuid"},"example":"2f940ade-912c-4a85-a2b5-eec8a9ae4342"},{"$ref":"#\/components\/parameters\/ResponseFormat"}],"requestBody":{"required":true,"description":"Objeto JSON p\u00fablico, completo o parcial. M\u00e1ximo 262144 bytes. Datos ausentes permiten borradores; valores enviados inv\u00e1lidos producen 422.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/DecaRequest"},"examples":{"shipper":{"summary":"Completo: mi empresa es el cargador","description":"shipper se rellena desde la empresa. Datos ficticios; NIF de contraparte v\u00e1lido. Devuelve issued y PDF.","value":{"companyRole":"shipper","customerReference":"PED-1042","transportDate":"2026-10-15","carrier":{"name":"Transportes de ejemplo","taxId":"B87654323","address":"Calle Industria 8, Sevilla"},"vehicle":{"plate":"1234 ABC","articulated":false},"specialTransport":{"enabled":false},"deliveries":[{"recipientName":"Almac\u00e9n de ejemplo","originAddress":"Calle Comercio 1, Sevilla","destinationAddress":"Calle Mayor 2, Madrid","goods":"Material embalado","weightKg":2400.5,"packages":12}]}},"carrier":{"summary":"Completo: mi empresa es el transportista","description":"carrier se rellena desde la empresa. Incluye remolque y transporte especial.","value":{"companyRole":"carrier","customerReference":"PED-1043","transportDate":"2026-10-15","shipper":{"name":"Cargador de ejemplo","taxId":"B87654323","address":"Calle Comercio 1, Sevilla"},"vehicle":{"plate":"5678 DEF","articulated":true,"trailerPlate":"R1234 ABC"},"specialTransport":{"enabled":true,"authorization":"AUT-2026-001"},"driverName":"Ana de ejemplo","deliveries":[{"originAddress":"Calle Comercio 1, Sevilla","destinationAddress":"Calle Mayor 2, Madrid","goods":"Maquinaria embalada","weightKg":8000,"packages":2,"unloadingDate":"2026-10-16"}]}},"alternativeWeight":{"summary":"Completo: magnitud alternativa","description":"weightDescription sustituye al peso en kg.","value":{"companyRole":"shipper","customerReference":"PED-1044","transportDate":"2026-10-15","carrier":{"name":"Transportes de ejemplo","taxId":"B87654323","address":"Calle Industria 8, Sevilla"},"vehicle":{"plate":"1234 ABC","articulated":false},"specialTransport":{"enabled":false},"deliveries":[{"originAddress":"Calle Comercio 1, Sevilla","destinationAddress":"Calle Mayor 2, Madrid","goods":"Carga de volumen conocido","weightDescription":"12 m\u00b3","packages":3}]}},"draft":{"summary":"Incompleto: borrador sin PDF","description":"Faltan NIF del transportista, matr\u00edcula y detalles del env\u00edo. Devuelve draft y pendingFields; nunca document, pdf o url.","value":{"customerReference":"PED-PENDIENTE","transportDate":"2026-10-15","carrier":{"name":"Transportes de ejemplo"},"deliveries":[{"originAddress":"Calle Comercio 1, Sevilla"}]}}}}}},"responses":{"201":{"description":"Documento creado o simulado. status=draft: version=0 y pendingFields, sin PDF ni enlace. status=issued: version=1 y documento p\u00fablico; producci\u00f3n devuelve una URL directa al PDF, sandbox devuelve el PDF de prueba en base64. El PDF de sandbox del ejemplo se abrevia a su cabecera.","headers":{"X-RateLimit-Limit":{"$ref":"#\/components\/headers\/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#\/components\/headers\/RateLimitRemaining"}},"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/DecaResponse"},"examples":{"productionIssued":{"summary":"Producci\u00f3n: emitido con URL de descarga","value":{"environment":"production","data":{"id":"7f84ca0e-fd39-454f-926c-338f19ac8c61","companyId":"2f940ade-912c-4a85-a2b5-eec8a9ae4342","reference":"DECA-01ARZ3NDEKTSV4RRFFQ69G5FAV","status":"issued","version":1,"document":{"companyRole":"shipper","customerReference":"PED-1042","transportDate":"2026-10-15","carrier":{"name":"Transportes de ejemplo","taxId":"B87654323","address":"Calle Industria 8, Sevilla"},"vehicle":{"plate":"1234 ABC","articulated":false,"trailerPlate":null},"specialTransport":{"enabled":false,"authorization":null},"deliveries":[{"recipientName":"Almac\u00e9n de ejemplo","originAddress":"Calle Comercio 1, Sevilla","destinationAddress":"Calle Mayor 2, Madrid","goods":"Material embalado","weightKg":2400.5,"packages":12,"weightDescription":null,"unloadingDate":null}],"shipper":{"name":"Empresa API","taxId":"B12345674","address":"Calle Mayor 12, Madrid, Espa\u00f1a"}},"url":"https:\/\/deca.example\/deca\/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.pdf","pdf":{"fileName":"DECA-01ARZ3NDEKTSV4RRFFQ69G5FAV-v1.pdf","contentType":"application\/pdf","sha256":"e5c62df5dab5c87b6a015ef3d43597074d1eec433b15f51aec63b8582d0e4ab4"}}}},"productionDraft":{"summary":"Producci\u00f3n: borrador sin PDF","value":{"environment":"production","data":{"id":"0f359e06-57f9-4827-afef-eab01a33255e","companyId":"2f940ade-912c-4a85-a2b5-eec8a9ae4342","reference":"DECA-01ARZ3NDEKTSV4RRFFQ69G5FAW","status":"draft","version":0,"pendingFields":["carrier.taxId","vehicle.plate","deliveries.0.destinationAddress","deliveries.0.goods","deliveries.0.weightKg"]}}},"sandboxIssued":{"summary":"Sandbox: emitido de prueba, PDF abreviado","value":{"environment":"sandbox","data":{"id":null,"companyId":"2f940ade-912c-4a85-a2b5-eec8a9ae4342","reference":"PRUEBA-01ARZ3NDEKTSV4RRFFQ69G5FAV","status":"issued","version":1,"document":{"companyRole":"shipper","customerReference":"PED-1042","transportDate":"2026-10-15","carrier":{"name":"Transportes de ejemplo","taxId":"B87654323","address":"Calle Industria 8, Sevilla"},"vehicle":{"plate":"1234 ABC","articulated":false,"trailerPlate":null},"specialTransport":{"enabled":false,"authorization":null},"deliveries":[{"recipientName":"Almac\u00e9n de ejemplo","originAddress":"Calle Comercio 1, Sevilla","destinationAddress":"Calle Mayor 2, Madrid","goods":"Material embalado","weightKg":2400.5,"packages":12,"weightDescription":null,"unloadingDate":null}],"shipper":{"name":"Empresa API","taxId":"B12345674","address":"Calle Mayor 12, Madrid, Espa\u00f1a"}},"url":null,"pdf":{"fileName":"PRUEBA-01ARZ3NDEKTSV4RRFFQ69G5FAV-v1.pdf","contentType":"application\/pdf","sha256":"e5c62df5dab5c87b6a015ef3d43597074d1eec433b15f51aec63b8582d0e4ab4","encoding":"base64","content":"JVBERi0xLjQK"}}}},"sandboxDraft":{"summary":"Sandbox: borrador simulado sin PDF","value":{"environment":"sandbox","data":{"id":null,"companyId":"2f940ade-912c-4a85-a2b5-eec8a9ae4342","reference":"PRUEBA-01ARZ3NDEKTSV4RRFFQ69G5FAW","status":"draft","version":0,"pendingFields":["carrier.taxId","vehicle.plate","deliveries.0.destinationAddress","deliveries.0.goods","deliveries.0.weightKg"]}}}}},"application\/xml":{"schema":{"type":"string","description":"XML con ra\u00edz response, listas item con atributo key y nulos null=\"true\". Los caracteres incompatibles con XML 1.0 se sustituyen por \ufffd solo en esta representaci\u00f3n."},"examples":{"productionIssued":{"summary":"Producci\u00f3n: emitido con URL","value":"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response><environment>production<\/environment><data><id>7f84ca0e-fd39-454f-926c-338f19ac8c61<\/id><companyId>2f940ade-912c-4a85-a2b5-eec8a9ae4342<\/companyId><reference>DECA-01ARZ3NDEKTSV4RRFFQ69G5FAV<\/reference><status>issued<\/status><version>1<\/version><document><companyRole>shipper<\/companyRole><customerReference>PED-1042<\/customerReference><transportDate>2026-10-15<\/transportDate><carrier><name>Transportes de ejemplo<\/name><taxId>B87654323<\/taxId><address>Calle Industria 8, Sevilla<\/address><\/carrier><vehicle><plate>1234 ABC<\/plate><articulated>false<\/articulated><trailerPlate null=\"true\"\/><\/vehicle><specialTransport><enabled>false<\/enabled><authorization null=\"true\"\/><\/specialTransport><deliveries><item key=\"0\"><recipientName>Almac\u00e9n de ejemplo<\/recipientName><originAddress>Calle Comercio 1, Sevilla<\/originAddress><destinationAddress>Calle Mayor 2, Madrid<\/destinationAddress><goods>Material embalado<\/goods><weightKg>2400.5<\/weightKg><packages>12<\/packages><weightDescription null=\"true\"\/><unloadingDate null=\"true\"\/><\/item><\/deliveries><shipper><name>Empresa API<\/name><taxId>B12345674<\/taxId><address>Calle Mayor 12, Madrid, Espa\u00f1a<\/address><\/shipper><\/document><url>https:\/\/deca.example\/deca\/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.pdf<\/url><pdf><fileName>DECA-01ARZ3NDEKTSV4RRFFQ69G5FAV-v1.pdf<\/fileName><contentType>application\/pdf<\/contentType><sha256>e5c62df5dab5c87b6a015ef3d43597074d1eec433b15f51aec63b8582d0e4ab4<\/sha256><\/pdf><\/data><\/response>\n"},"productionDraft":{"summary":"Producci\u00f3n: borrador","value":"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response><environment>production<\/environment><data><id>0f359e06-57f9-4827-afef-eab01a33255e<\/id><companyId>2f940ade-912c-4a85-a2b5-eec8a9ae4342<\/companyId><reference>DECA-01ARZ3NDEKTSV4RRFFQ69G5FAW<\/reference><status>draft<\/status><version>0<\/version><pendingFields><item key=\"0\">carrier.taxId<\/item><item key=\"1\">vehicle.plate<\/item><item key=\"2\">deliveries.0.destinationAddress<\/item><item key=\"3\">deliveries.0.goods<\/item><item key=\"4\">deliveries.0.weightKg<\/item><\/pendingFields><\/data><\/response>\n"},"sandboxIssued":{"summary":"Sandbox: emitido de prueba","value":"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response><environment>sandbox<\/environment><data><id null=\"true\"\/><companyId>2f940ade-912c-4a85-a2b5-eec8a9ae4342<\/companyId><reference>PRUEBA-01ARZ3NDEKTSV4RRFFQ69G5FAV<\/reference><status>issued<\/status><version>1<\/version><document><companyRole>shipper<\/companyRole><customerReference>PED-1042<\/customerReference><transportDate>2026-10-15<\/transportDate><carrier><name>Transportes de ejemplo<\/name><taxId>B87654323<\/taxId><address>Calle Industria 8, Sevilla<\/address><\/carrier><vehicle><plate>1234 ABC<\/plate><articulated>false<\/articulated><trailerPlate null=\"true\"\/><\/vehicle><specialTransport><enabled>false<\/enabled><authorization null=\"true\"\/><\/specialTransport><deliveries><item key=\"0\"><recipientName>Almac\u00e9n de ejemplo<\/recipientName><originAddress>Calle Comercio 1, Sevilla<\/originAddress><destinationAddress>Calle Mayor 2, Madrid<\/destinationAddress><goods>Material embalado<\/goods><weightKg>2400.5<\/weightKg><packages>12<\/packages><weightDescription null=\"true\"\/><unloadingDate null=\"true\"\/><\/item><\/deliveries><shipper><name>Empresa API<\/name><taxId>B12345674<\/taxId><address>Calle Mayor 12, Madrid, Espa\u00f1a<\/address><\/shipper><\/document><url null=\"true\"\/><pdf><fileName>PRUEBA-01ARZ3NDEKTSV4RRFFQ69G5FAV-v1.pdf<\/fileName><contentType>application\/pdf<\/contentType><sha256>e5c62df5dab5c87b6a015ef3d43597074d1eec433b15f51aec63b8582d0e4ab4<\/sha256><encoding>base64<\/encoding><content>JVBERi0xLjQK<\/content><\/pdf><\/data><\/response>\n"},"sandboxDraft":{"summary":"Sandbox: borrador simulado","value":"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response><environment>sandbox<\/environment><data><id null=\"true\"\/><companyId>2f940ade-912c-4a85-a2b5-eec8a9ae4342<\/companyId><reference>PRUEBA-01ARZ3NDEKTSV4RRFFQ69G5FAW<\/reference><status>draft<\/status><version>0<\/version><pendingFields><item key=\"0\">carrier.taxId<\/item><item key=\"1\">vehicle.plate<\/item><item key=\"2\">deliveries.0.destinationAddress<\/item><item key=\"3\">deliveries.0.goods<\/item><item key=\"4\">deliveries.0.weightKg<\/item><\/pendingFields><\/data><\/response>\n"}}}}},"400":{"$ref":"#\/components\/responses\/BadRequest"},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"404":{"$ref":"#\/components\/responses\/NotFound"},"406":{"$ref":"#\/components\/responses\/NotAcceptable"},"413":{"$ref":"#\/components\/responses\/PayloadTooLarge"},"415":{"$ref":"#\/components\/responses\/UnsupportedMediaType"},"422":{"$ref":"#\/components\/responses\/UnprocessableEntity"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"},"500":{"$ref":"#\/components\/responses\/InternalServerError"}}}}},"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Pega solo el secreto, sin el prefijo Bearer. Sandbox utiliza deca_test_\u2026 y producci\u00f3n deca_live_\u2026. Token de entorno obligatorio; no se aceptan sesiones del navegador."}},"parameters":{"ResponseFormat":{"name":"format","in":"query","required":false,"description":"Formato de respuesta. Si se indica, tiene prioridad sobre Accept. No cambia el formato del cuerpo: siempre JSON. En XML, los caracteres incompatibles con XML 1.0 se sustituyen por U+FFFD (\ufffd); JSON y el PDF conservan los datos originales.","schema":{"type":"string","enum":["json","xml"]}}},"headers":{"RateLimitLimit":{"description":"L\u00edmite aplicado a esta respuesta (30 por cuenta\/entorno o 120 por IP).","schema":{"type":"integer","minimum":1},"example":30},"RateLimitRemaining":{"description":"Peticiones restantes en la ventana del l\u00edmite aplicado.","schema":{"type":"integer","minimum":0},"example":29},"RateLimitReset":{"description":"Instante de reapertura del l\u00edmite, como Unix timestamp en segundos. Se env\u00eda con 429.","schema":{"type":"integer"},"example":1792065660},"RetryAfter":{"description":"Segundos que debes esperar antes de la siguiente petici\u00f3n. Se env\u00eda con 429.","schema":{"type":"integer","minimum":0},"example":60}},"schemas":{"DecaRequest":{"type":"object","additionalProperties":false,"description":"Datos del documento agrupados por entidad y en camelCase. Admite informaci?n parcial: si faltan requisitos de emisi?n, se crea un borrador. Los valores enviados deben ser v?lidos. Solo se admiten los campos documentados, tambi?n dentro de objetos y env?os.","properties":{"companyRole":{"type":["string","null"],"enum":["shipper","carrier",null],"default":"shipper","description":"Papel de la empresa seleccionada: cargador (shipper) o transportista (carrier). Omitido o null equivale a shipper. Nombre, NIF y domicilio de ese papel se toman siempre de la empresa, sustituyendo los que env\u00edes."},"customerReference":{"type":["string","null"],"maxLength":100,"description":"Referencia de tu sistema. No es \u00fanica ni evita emisiones o borradores duplicados."},"transportDate":{"type":["string","null"],"format":"date","description":"Fecha de transporte, YYYY-MM-DD. Necesaria para emitir; puede omitirse o ser null en un borrador."},"shipper":{"type":["object","null"],"additionalProperties":false,"description":"Identidad de cargador o transportista. La de tu empresa se rellena desde el panel; proporciona la contraparte. null equivale a ausencia.","properties":{"name":{"type":["string","null"],"maxLength":200,"description":"Nombre legal. Necesario para emitir, salvo el papel de tu empresa que se rellena autom\u00e1ticamente."},"taxId":{"type":["string","null"],"maxLength":32,"description":"NIF, NIE o CIF espa\u00f1ol con control v\u00e1lido. Necesario para emitir. Un valor no vac\u00edo con control inv\u00e1lido devuelve 422; puede omitirse al crear un borrador."},"address":{"type":["string","null"],"maxLength":500,"description":"Domicilio. Necesario para el cargador; opcional para el transportista externo. El papel de tu empresa toma su domicilio del panel."}}},"carrier":{"type":["object","null"],"additionalProperties":false,"description":"Identidad de cargador o transportista. La de tu empresa se rellena desde el panel; proporciona la contraparte. null equivale a ausencia.","properties":{"name":{"type":["string","null"],"maxLength":200,"description":"Nombre legal. Necesario para emitir, salvo el papel de tu empresa que se rellena autom\u00e1ticamente."},"taxId":{"type":["string","null"],"maxLength":32,"description":"NIF, NIE o CIF espa\u00f1ol con control v\u00e1lido. Necesario para emitir. Un valor no vac\u00edo con control inv\u00e1lido devuelve 422; puede omitirse al crear un borrador."},"address":{"type":["string","null"],"maxLength":500,"description":"Domicilio. Necesario para el cargador; opcional para el transportista externo. El papel de tu empresa toma su domicilio del panel."}}},"vehicle":{"type":["object","null"],"additionalProperties":false,"description":"Datos del veh\u00edculo. null equivale a ausencia.","properties":{"plate":{"type":["string","null"],"maxLength":20,"description":"Matr\u00edcula necesaria para emitir. Letras y n\u00fameros con al menos un n\u00famero; espacios o guiones entre grupos. Un valor no vac\u00edo con formato inv\u00e1lido devuelve 422."},"articulated":{"type":"boolean","default":false,"description":"Omitido equivale a false; null no se admite. Si es true, trailerPlate es necesaria para emitir."},"trailerPlate":{"type":["string","null"],"maxLength":20,"description":"Matr\u00edcula del remolque. Si articulated=true y falta, el documento queda en borrador. En caso contrario se normaliza a null. Usa el mismo formato que vehicle.plate."}}},"specialTransport":{"type":["object","null"],"additionalProperties":false,"description":"Transporte especial. null equivale a ausencia.","properties":{"enabled":{"type":"boolean","default":false,"description":"Omitido equivale a false; null no se admite. Si es true, authorization es necesaria para emitir."},"authorization":{"type":["string","null"],"maxLength":100,"description":"Autorizaci\u00f3n del transporte especial. Si enabled=true y falta, se crea un borrador. En caso contrario se normaliza a null."}}},"driverName":{"type":["string","null"],"maxLength":150,"description":"Nombre del conductor, opcional."},"notes":{"type":["string","null"],"maxLength":4000,"description":"Observaciones del transporte, opcionales."},"deliveries":{"type":["array","null"],"minItems":0,"maxItems":30,"description":"Lista JSON de env\u00edos, no un objeto con claves propias. Omitida, null o [] deja el documento como borrador. Para emitir debe incluir de 1 a 30 env\u00edos completos.","items":{"type":"object","additionalProperties":false,"description":"Env\u00edo. Puede estar incompleto en una solicitud: origen, destino, mercanc\u00eda y peso o magnitud alternativa son necesarios para emitir. El elemento debe ser un objeto; no se admite null.","properties":{"recipientName":{"type":["string","null"],"maxLength":200,"description":"Nombre del destinatario, opcional."},"originAddress":{"type":["string","null"],"maxLength":500,"description":"Direcci\u00f3n de origen. Necesaria para emitir."},"destinationAddress":{"type":["string","null"],"maxLength":500,"description":"Direcci\u00f3n de destino. Necesaria para emitir."},"goods":{"type":["string","null"],"maxLength":1000,"description":"Descripci\u00f3n de la mercanc\u00eda. Necesaria para emitir."},"weightKg":{"type":["number","null"],"minimum":0.001,"maximum":999999999,"description":"Peso en kg, m\u00ednimo 0.001 (un gramo). Necesario para emitir salvo que exista weightDescription. Usa un n\u00famero JSON con punto decimal."},"weightDescription":{"type":["string","null"],"maxLength":200,"description":"Magnitud alternativa, por ejemplo 12 m\u00b3. Necesaria para emitir si falta weightKg. Cuando hay kg, la respuesta la normaliza a null."},"packages":{"type":["integer","null"],"minimum":1,"maximum":9999999,"description":"N\u00famero de bultos, opcional."},"unloadingDate":{"type":["string","null"],"format":"date","description":"Fecha de descarga opcional, YYYY-MM-DD. Si se indica, no puede ser anterior a transportDate."}}}}}},"CompanyListResponse":{"type":"object","additionalProperties":false,"required":["data","environment"],"properties":{"data":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["id","name","taxId"],"properties":{"id":{"type":"string","format":"uuid","description":"UUID v4 p\u00fablico y estable de la empresa, obtenido mediante GET \/companies."},"name":{"type":"string","maxLength":200,"description":"Nombre de empresa."},"taxId":{"type":"string","maxLength":32,"description":"NIF de la empresa."}}}},"environment":{"type":"string","enum":["sandbox","production"]}}},"DecaResponse":{"type":"object","additionalProperties":false,"required":["environment","data"],"properties":{"environment":{"type":"string","enum":["sandbox","production"]},"data":{"oneOf":[{"type":"object","additionalProperties":false,"required":["id","companyId","reference","status","version","pendingFields"],"description":"Faltan datos necesarios para emitir. En producci\u00f3n se guarda el borrador; en sandbox solo se simula. No hay document, pdf ni url, y no se genera ning\u00fan archivo ni revisi\u00f3n.","properties":{"id":{"type":["string","null"],"description":"UUID v4 p\u00fablico y estable del documento guardado en producci\u00f3n; null en sandbox.","format":"uuid"},"companyId":{"type":"string","format":"uuid","description":"UUID v4 p\u00fablico y estable de la empresa, obtenido mediante GET \/companies."},"reference":{"type":"string","description":"Referencia estable del documento: DECA-ULID para nuevos documentos de producci\u00f3n y PRUEBA-ULID en sandbox. Las referencias hist\u00f3ricas siguen siendo v\u00e1lidas."},"status":{"type":"string","const":"draft"},"version":{"type":"integer","const":0},"pendingFields":{"type":"array","minItems":1,"items":{"type":"string"},"description":"Rutas de campos p\u00fablicos que faltan, por ejemplo carrier.taxId o deliveries.0.goods. Completa el borrador desde el panel; repetir POST crea un documento nuevo."}},"title":"Borrador"},{"type":"object","additionalProperties":false,"required":["id","companyId","reference","status","version","document","url","pdf"],"description":"Documento completo. Producci\u00f3n lo archiva y devuelve una URL directa al PDF. Sandbox devuelve el PDF de prueba en base64, sin persistencia.","properties":{"id":{"type":["string","null"],"description":"UUID v4 p\u00fablico y estable del documento guardado en producci\u00f3n; null en sandbox.","format":"uuid"},"companyId":{"type":"string","format":"uuid","description":"UUID v4 p\u00fablico y estable de la empresa, obtenido mediante GET \/companies."},"reference":{"type":"string","description":"Referencia estable del documento: DECA-ULID para nuevos documentos de producci\u00f3n y PRUEBA-ULID en sandbox. Las referencias hist\u00f3ricas siguen siendo v\u00e1lidas."},"status":{"type":"string","const":"issued"},"version":{"type":"integer","const":1},"document":{"type":"object","additionalProperties":false,"description":"Datos finales del documento emitido usando exclusivamente el contrato p\u00fablico. La identidad propia viene de la empresa; NIF y matr\u00edculas se normalizan a may\u00fasculas. Los datos no aplicables son null.","required":["companyRole","transportDate","shipper","carrier","vehicle","specialTransport","deliveries"],"properties":{"companyRole":{"type":"string","enum":["shipper","carrier"]},"customerReference":{"type":["string","null"],"maxLength":100,"description":"Referencia de tu sistema. No es \u00fanica ni evita emisiones o borradores duplicados."},"transportDate":{"type":"string","format":"date","description":"Fecha de transporte en formato YYYY-MM-DD."},"shipper":{"type":"object","additionalProperties":false,"required":["name","taxId","address"],"properties":{"name":{"type":"string","maxLength":200},"taxId":{"type":"string","maxLength":32},"address":{"type":"string","maxLength":500}}},"carrier":{"type":"object","additionalProperties":false,"required":["name","taxId"],"properties":{"name":{"type":"string","maxLength":200},"taxId":{"type":"string","maxLength":32},"address":{"type":["string","null"],"maxLength":500,"description":"Domicilio del transportista."}}},"vehicle":{"type":"object","additionalProperties":false,"required":["plate","articulated"],"properties":{"plate":{"type":"string","maxLength":20,"description":"Matr?cula del veh?culo del documento emitido."},"articulated":{"type":"boolean"},"trailerPlate":{"type":["string","null"],"maxLength":20,"description":"Matr\u00edcula del remolque o null cuando articulated=false. Usa el mismo formato que vehicle.plate."}},"allOf":[{"if":{"properties":{"articulated":{"const":true}},"required":["articulated"]},"then":{"required":["trailerPlate"],"properties":{"trailerPlate":{"type":"string"}}}}]},"specialTransport":{"type":"object","additionalProperties":false,"required":["enabled"],"properties":{"enabled":{"type":"boolean"},"authorization":{"type":["string","null"],"maxLength":100,"description":"Autorizaci\u00f3n o null cuando enabled=false."}},"allOf":[{"if":{"properties":{"enabled":{"const":true}},"required":["enabled"]},"then":{"required":["authorization"],"properties":{"authorization":{"type":"string"}}}}]},"driverName":{"type":["string","null"],"maxLength":150,"description":"Nombre del conductor, opcional."},"notes":{"type":["string","null"],"maxLength":4000,"description":"Observaciones del transporte, opcionales."},"deliveries":{"type":"array","minItems":1,"maxItems":30,"items":{"type":"object","additionalProperties":false,"required":["originAddress","destinationAddress","goods"],"properties":{"recipientName":{"type":["string","null"],"maxLength":200,"description":"Nombre del destinatario, opcional."},"originAddress":{"type":"string","maxLength":500},"destinationAddress":{"type":"string","maxLength":500},"goods":{"type":"string","maxLength":1000},"weightKg":{"type":["number","null"],"exclusiveMinimum":0,"maximum":999999999,"description":"Peso positivo en kg. Necesario para emitir salvo que exista weightDescription. Usa un n\u00famero JSON con punto decimal."},"weightDescription":{"type":["string","null"],"maxLength":200,"description":"Magnitud alternativa, por ejemplo 12 m\u00b3. Necesaria para emitir si falta weightKg. Cuando hay kg, la respuesta la normaliza a null."},"packages":{"type":["integer","null"],"minimum":1,"maximum":9999999,"description":"N\u00famero de bultos, opcional."},"unloadingDate":{"type":["string","null"],"format":"date","description":"Fecha de descarga opcional, YYYY-MM-DD. Si se indica, no puede ser anterior a transportDate."}},"anyOf":[{"required":["weightKg"],"properties":{"weightKg":{"type":"number","exclusiveMinimum":0,"maximum":999999999}}},{"required":["weightDescription"],"properties":{"weightDescription":{"type":"string","maxLength":200}}}]}}}},"url":{"type":["string","null"],"format":"uri","description":"En producci\u00f3n, enlace p\u00fablico directo de acceso y descarga del PDF; no requiere Bearer ni iniciar sesi\u00f3n. En sandbox es null. Revocar el token de API no revoca este enlace."},"pdf":{"oneOf":[{"type":"object","additionalProperties":false,"required":["fileName","contentType","sha256"],"description":"Metadatos del PDF archivado. En producci\u00f3n no se incluye el archivo en la respuesta: desc\u00e1rgalo directamente desde data.url.","properties":{"fileName":{"type":"string"},"contentType":{"type":"string","const":"application\/pdf"},"sha256":{"type":"string","description":"SHA-256 de los bytes del PDF descargado."}}},{"type":"object","additionalProperties":false,"required":["fileName","contentType","sha256","encoding","content"],"description":"PDF de prueba marcado PRUEBA \u00b7 SIN VALIDEZ. Solo en sandbox emitido: no se guarda ni tiene URL. Decodifica content desde base64 y comprueba SHA-256 sobre los bytes.","properties":{"fileName":{"type":"string"},"contentType":{"type":"string","const":"application\/pdf"},"sha256":{"type":"string","description":"SHA-256 de los bytes del PDF de prueba decodificado desde base64."},"encoding":{"type":"string","const":"base64"},"content":{"type":"string","contentEncoding":"base64","contentMediaType":"application\/pdf"}}}]}},"title":"Emitido"}]}},"allOf":[{"if":{"properties":{"environment":{"const":"sandbox"}},"required":["environment"]},"then":{"properties":{"data":{"properties":{"id":{"type":"null"}},"if":{"properties":{"status":{"const":"issued"}},"required":["status"]},"then":{"properties":{"url":{"type":"null"},"pdf":{"type":"object","additionalProperties":false,"required":["fileName","contentType","sha256","encoding","content"],"description":"PDF de prueba marcado PRUEBA \u00b7 SIN VALIDEZ. Solo en sandbox emitido: no se guarda ni tiene URL. Decodifica content desde base64 y comprueba SHA-256 sobre los bytes.","properties":{"fileName":{"type":"string"},"contentType":{"type":"string","const":"application\/pdf"},"sha256":{"type":"string","description":"SHA-256 de los bytes del PDF de prueba decodificado desde base64."},"encoding":{"type":"string","const":"base64"},"content":{"type":"string","contentEncoding":"base64","contentMediaType":"application\/pdf"}}}}}}}}},{"if":{"properties":{"environment":{"const":"production"}},"required":["environment"]},"then":{"properties":{"data":{"properties":{"id":{"type":"string","format":"uuid","description":"UUID v4 p\u00fablico y estable del documento guardado."}},"if":{"properties":{"status":{"const":"issued"}},"required":["status"]},"then":{"properties":{"url":{"type":"string","format":"uri"},"pdf":{"type":"object","additionalProperties":false,"required":["fileName","contentType","sha256"],"description":"Metadatos del PDF archivado. En producci\u00f3n no se incluye el archivo en la respuesta: desc\u00e1rgalo directamente desde data.url.","properties":{"fileName":{"type":"string"},"contentType":{"type":"string","const":"application\/pdf"},"sha256":{"type":"string","description":"SHA-256 de los bytes del PDF descargado."}}}}}}}}}]},"DecaListResponse":{"type":"object","additionalProperties":false,"required":["environment","data","meta"],"properties":{"environment":{"type":"string","enum":["sandbox","production"]},"data":{"type":"array","items":{"oneOf":[{"type":"object","additionalProperties":false,"required":["id","companyId","reference","status","version","createdAt","updatedAt","document","pendingFields"],"description":"Borrador guardado, con sus datos parciales y requisitos pendientes o inv\u00e1lidos. Nunca incluye pdf ni url.","properties":{"id":{"type":"string","description":"UUID v4 p\u00fablico y estable del documento guardado.","format":"uuid"},"companyId":{"type":"string","format":"uuid","description":"UUID v4 p\u00fablico y estable de la empresa, obtenido mediante GET \/companies."},"reference":{"type":"string","description":"Referencia estable del documento: DECA-ULID para nuevos documentos de producci\u00f3n y PRUEBA-ULID en sandbox. Las referencias hist\u00f3ricas siguen siendo v\u00e1lidas."},"status":{"type":"string","const":"draft"},"version":{"type":"integer","const":0},"createdAt":{"type":"string","format":"date-time","description":"Fecha y hora UTC de creaci\u00f3n del documento. Determina el periodo consultado; no es la fecha de transporte ni de actualizaci\u00f3n."},"updatedAt":{"type":"string","format":"date-time","description":"Fecha y hora UTC de la \u00faltima actualizaci\u00f3n. No determina el periodo from\u2013to."},"document":{"type":"object","additionalProperties":false,"description":"Datos parciales del borrador. Puede contener campos pendientes o valores por corregir; consulta pendingFields.","properties":{"companyRole":{"type":["string","null"],"enum":["shipper","carrier",null],"description":"Papel de la empresa en los datos guardados."},"customerReference":{"type":["string","null"],"maxLength":100},"transportDate":{"type":["string","null"],"format":"date","description":"Fecha de transporte almacenada, YYYY-MM-DD, o null si est\u00e1 pendiente."},"shipper":{"type":["object","null"],"additionalProperties":false,"description":"Identidad almacenada, posiblemente incompleta. Se muestra tal como est\u00e1 en el borrador.","properties":{"name":{"type":["string","null"],"maxLength":200,"description":"Nombre guardado del cargador o transportista."},"taxId":{"type":["string","null"],"maxLength":32,"description":"Identificaci\u00f3n fiscal almacenada; puede estar pendiente o incompleta."},"address":{"type":["string","null"],"maxLength":500,"description":"Domicilio almacenado."}}},"carrier":{"type":["object","null"],"additionalProperties":false,"description":"Identidad almacenada, posiblemente incompleta. Se muestra tal como est\u00e1 en el borrador.","properties":{"name":{"type":["string","null"],"maxLength":200,"description":"Nombre guardado del cargador o transportista."},"taxId":{"type":["string","null"],"maxLength":32,"description":"Identificaci\u00f3n fiscal almacenada; puede estar pendiente o incompleta."},"address":{"type":["string","null"],"maxLength":500,"description":"Domicilio almacenado."}}},"vehicle":{"type":["object","null"],"additionalProperties":false,"description":"Datos almacenados del veh\u00edculo, posiblemente pendientes.","properties":{"plate":{"type":["string","null"],"maxLength":20,"description":"Matr\u00edcula almacenada; puede estar pendiente o incompleta."},"articulated":{"type":"boolean","default":false,"description":"Indica si el veh\u00edculo del borrador es articulado."},"trailerPlate":{"type":["string","null"],"maxLength":20,"description":"Matr\u00edcula almacenada del remolque, posiblemente pendiente."}}},"specialTransport":{"type":["object","null"],"additionalProperties":false,"description":"Datos almacenados de transporte especial.","properties":{"enabled":{"type":"boolean","default":false,"description":"Indica si el borrador es un transporte especial."},"authorization":{"type":["string","null"],"maxLength":100,"description":"Autorizaci\u00f3n almacenada, posiblemente pendiente."}}},"driverName":{"type":["string","null"],"maxLength":150,"description":"Nombre del conductor, opcional."},"notes":{"type":["string","null"],"maxLength":4000,"description":"Observaciones del transporte, opcionales."},"deliveries":{"type":["array","null"],"maxItems":30,"description":"Env\u00edos parciales almacenados; pueden faltar datos necesarios para emitir.","items":{"type":"object","additionalProperties":false,"description":"Datos almacenados de un env\u00edo parcial.","properties":{"recipientName":{"type":["string","null"],"maxLength":200,"description":"Nombre del destinatario, opcional."},"originAddress":{"type":["string","null"],"maxLength":500,"description":"Direcci\u00f3n de origen."},"destinationAddress":{"type":["string","null"],"maxLength":500,"description":"Direcci\u00f3n de destino."},"goods":{"type":["string","null"],"maxLength":1000,"description":"Descripci\u00f3n de la mercanc\u00eda."},"weightKg":{"type":["number","string","null"],"description":"Peso en kg, representado como n\u00famero o texto num\u00e9rico."},"weightDescription":{"type":["string","null"],"maxLength":200,"description":"Magnitud alternativa, por ejemplo 12 m\u00b3. Necesaria para emitir si falta weightKg. Cuando hay kg, la respuesta la normaliza a null."},"packages":{"type":["integer","string","null"],"description":"N\u00famero de bultos, representado como entero o texto num\u00e9rico."},"unloadingDate":{"type":["string","null"],"format":"date","description":"Fecha de descarga almacenada, YYYY-MM-DD, o null si est? pendiente. pendingFields indica si debe corregirse."}}}}}},"pendingFields":{"type":"array","items":{"type":"string"},"description":"Rutas de campos p\u00fablicos pendientes o inv\u00e1lidos, por ejemplo carrier.taxId, vehicle.plate o deliveries.0.goods. No contiene nombres internos."}},"title":"Borrador"},{"type":"object","additionalProperties":false,"required":["id","companyId","reference","status","version","createdAt","updatedAt","document","url","pdf"],"description":"Documento emitido. document, version, url y pdf corresponden a la \u00faltima versi\u00f3n archivada, que puede ser superior a 1. La consulta solo devuelve datos y metadatos, sin leer ni generar el archivo PDF.","properties":{"id":{"type":"string","description":"UUID v4 p\u00fablico y estable del documento guardado.","format":"uuid"},"companyId":{"type":"string","format":"uuid","description":"UUID v4 p\u00fablico y estable de la empresa, obtenido mediante GET \/companies."},"reference":{"type":"string","description":"Referencia estable del documento: DECA-ULID para nuevos documentos de producci\u00f3n y PRUEBA-ULID en sandbox. Las referencias hist\u00f3ricas siguen siendo v\u00e1lidas."},"status":{"type":"string","const":"issued"},"version":{"type":"integer","minimum":1,"description":"\u00daltima versi\u00f3n emitida; puede superar 1 tras modificar el documento desde el panel."},"createdAt":{"type":"string","format":"date-time","description":"Fecha y hora UTC de creaci\u00f3n del documento. Determina el periodo consultado; no es la fecha de transporte ni de actualizaci\u00f3n."},"updatedAt":{"type":"string","format":"date-time","description":"Fecha y hora UTC de la \u00faltima actualizaci\u00f3n. No determina el periodo from\u2013to."},"document":{"type":"object","additionalProperties":false,"description":"Datos de la \u00faltima versi\u00f3n emitida. weightKg y packages pueden contener n\u00fameros o texto num\u00e9rico.","required":["companyRole","transportDate","shipper","carrier","vehicle","specialTransport","deliveries"],"properties":{"companyRole":{"type":"string","enum":["shipper","carrier"]},"customerReference":{"type":["string","null"],"maxLength":100,"description":"Referencia de tu sistema. No es \u00fanica ni evita emisiones o borradores duplicados."},"transportDate":{"type":"string","format":"date","description":"Fecha de transporte en formato YYYY-MM-DD."},"shipper":{"type":"object","additionalProperties":false,"required":["name","taxId","address"],"properties":{"name":{"type":"string","maxLength":200},"taxId":{"type":"string","maxLength":32},"address":{"type":"string","maxLength":500}}},"carrier":{"type":"object","additionalProperties":false,"required":["name","taxId"],"properties":{"name":{"type":"string","maxLength":200},"taxId":{"type":"string","maxLength":32},"address":{"type":["string","null"],"maxLength":500,"description":"Domicilio del transportista."}}},"vehicle":{"type":"object","additionalProperties":false,"required":["plate","articulated"],"properties":{"plate":{"type":"string","maxLength":20,"description":"Matr?cula del veh?culo del documento emitido."},"articulated":{"type":"boolean"},"trailerPlate":{"type":["string","null"],"maxLength":20,"description":"Matr\u00edcula del remolque o null cuando articulated=false. Usa el mismo formato que vehicle.plate."}},"allOf":[{"if":{"properties":{"articulated":{"const":true}},"required":["articulated"]},"then":{"required":["trailerPlate"],"properties":{"trailerPlate":{"type":"string"}}}}]},"specialTransport":{"type":"object","additionalProperties":false,"required":["enabled"],"properties":{"enabled":{"type":"boolean"},"authorization":{"type":["string","null"],"maxLength":100,"description":"Autorizaci\u00f3n o null cuando enabled=false."}},"allOf":[{"if":{"properties":{"enabled":{"const":true}},"required":["enabled"]},"then":{"required":["authorization"],"properties":{"authorization":{"type":"string"}}}}]},"driverName":{"type":["string","null"],"maxLength":150,"description":"Nombre del conductor, opcional."},"notes":{"type":["string","null"],"maxLength":4000,"description":"Observaciones del transporte, opcionales."},"deliveries":{"type":"array","minItems":1,"maxItems":30,"items":{"type":"object","additionalProperties":false,"required":["originAddress","destinationAddress","goods"],"properties":{"recipientName":{"type":["string","null"],"maxLength":200,"description":"Nombre del destinatario, opcional."},"originAddress":{"type":"string","maxLength":500},"destinationAddress":{"type":"string","maxLength":500},"goods":{"type":"string","maxLength":1000},"weightKg":{"type":["number","string","null"],"exclusiveMinimum":0,"maximum":999999999,"description":"Peso v\u00e1lido almacenado en kg; puede ser n\u00famero o texto num\u00e9rico. Si se utiliz\u00f3 una magnitud alternativa, puede ser null."},"weightDescription":{"type":["string","null"],"maxLength":200,"description":"Magnitud alternativa, por ejemplo 12 m\u00b3. Necesaria para emitir si falta weightKg. Cuando hay kg, la respuesta la normaliza a null."},"packages":{"type":["integer","string","null"],"minimum":1,"maximum":9999999,"description":"Bultos almacenados; pueden ser entero, texto num\u00e9rico o null."},"unloadingDate":{"type":["string","null"],"format":"date","description":"Fecha de descarga opcional, YYYY-MM-DD. Si se indica, no puede ser anterior a transportDate."}},"anyOf":[{"required":["weightKg"],"properties":{"weightKg":{"type":["number","string"],"exclusiveMinimum":0,"maximum":999999999}}},{"required":["weightDescription"],"properties":{"weightDescription":{"type":"string","maxLength":200}}}],"description":"Datos del env\u00edo de la \u00faltima revisi\u00f3n emitida. Peso y bultos conservan su tipo almacenado, que puede ser num\u00e9rico o texto num\u00e9rico procedente del panel."}}}},"url":{"type":"string","format":"uri","description":"URL p\u00fablica directa para acceder y descargar el PDF de la \u00faltima versi\u00f3n, sin sesi\u00f3n ni Bearer."},"pdf":{"type":"object","additionalProperties":false,"required":["fileName","contentType","sha256"],"description":"Metadatos del PDF archivado. En producci\u00f3n no se incluye el archivo en la respuesta: desc\u00e1rgalo directamente desde data.url.","properties":{"fileName":{"type":"string"},"contentType":{"type":"string","const":"application\/pdf"},"sha256":{"type":"string","description":"SHA-256 de los bytes del PDF descargado."}}}},"title":"Emitido"}]},"description":"Documentos de la empresa que coinciden con los filtros, en orden de creaci\u00f3n descendente, con orden estable en los empates. Siempre vac\u00edo en sandbox."},"meta":{"type":"object","additionalProperties":false,"required":["currentPage","perPage","total","lastPage","period"],"properties":{"currentPage":{"type":"integer","minimum":1,"description":"P\u00e1gina solicitada."},"perPage":{"type":"integer","minimum":1,"maximum":100,"description":"Tama\u00f1o de p\u00e1gina aplicado."},"total":{"type":"integer","minimum":0,"description":"Total de documentos que cumplen todos los filtros, antes de paginar."},"lastPage":{"type":"integer","minimum":1,"description":"\u00daltima p\u00e1gina disponible. Vale 1 si total es 0."},"period":{"type":"object","additionalProperties":false,"required":["from","to","timeZone"],"description":"Periodo de creaci\u00f3n efectivamente aplicado. D\u00edas naturales inclusivos en UTC, hasta 30 d\u00edas; no equivale a un periodo de transportDate o updatedAt.","properties":{"from":{"type":"string","format":"date","description":"Primer d\u00eda incluido, YYYY-MM-DD."},"to":{"type":"string","format":"date","description":"\u00daltimo d\u00eda incluido, YYYY-MM-DD."},"timeZone":{"type":"string","const":"UTC","description":"Zona horaria utilizada para los l\u00edmites diarios."}}}}}},"allOf":[{"if":{"properties":{"environment":{"const":"sandbox"}},"required":["environment"]},"then":{"properties":{"data":{"type":"array","maxItems":0},"meta":{"properties":{"total":{"const":0},"lastPage":{"const":1}}}}}}]},"ErrorResponse":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"object","additionalProperties":false,"required":["status","message","details"],"properties":{"status":{"type":"integer","minimum":400,"maximum":599},"message":{"type":"string","description":"Mensaje humano que puede cambiar. Decide por estado HTTP y claves de campo."},"details":{"description":"En validaci\u00f3n: objeto que asocia rutas del contrato p\u00fablico (por ejemplo vehicle.plate o deliveries.0.goods) a listas de mensajes. La clave document identifica l\u00edmites de la empresa. Para los dem\u00e1s errores: lista vac\u00eda.","oneOf":[{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}},{"type":"array","maxItems":0}]}}}}}},"responses":{"BadRequest":{"description":"JSON mal formado o cuerpo que no es un objeto JSON.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ErrorResponse"},"example":{"error":{"status":400,"message":"El cuerpo no es un JSON v\u00e1lido.","details":[]}}},"application\/xml":{"schema":{"type":"string","description":"XML con ra\u00edz response; las listas usan item con atributo key y los nulos, null=\"true\"."},"example":"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response><error><status>400<\/status><message>El cuerpo no es un JSON v\u00e1lido.<\/message><details><\/details><\/error><\/response>\n"}}},"Unauthorized":{"description":"Token ausente, inv\u00e1lido, caducado o revocado; usuario sin verificar o cuenta cerrada.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ErrorResponse"},"example":{"error":{"status":401,"message":"Token inv\u00e1lido, caducado o revocado.","details":[]}}},"application\/xml":{"schema":{"type":"string","description":"XML con ra\u00edz response; las listas usan item con atributo key y los nulos, null=\"true\"."},"example":"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response><error><status>401<\/status><message>Token inv\u00e1lido, caducado o revocado.<\/message><details><\/details><\/error><\/response>\n"}}},"Forbidden":{"description":"Token de otro entorno, ninguna empresa habilitada para la API o ausencia de Pro activo en la empresa, en ambos entornos.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ErrorResponse"},"example":{"error":{"status":403,"message":"El token no corresponde a este entorno.","details":[]}}},"application\/xml":{"schema":{"type":"string","description":"XML con ra\u00edz response; las listas usan item con atributo key y los nulos, null=\"true\"."},"example":"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response><error><status>403<\/status><message>El token no corresponde a este entorno.<\/message><details><\/details><\/error><\/response>\n"}}},"NotFound":{"description":"Ruta o empresa inexistente, o empresa fuera del acceso permitido. Usa un ID obtenido por GET \/companies.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ErrorResponse"},"example":{"error":{"status":404,"message":"Recurso no encontrado.","details":[]}}},"application\/xml":{"schema":{"type":"string","description":"XML con ra\u00edz response; las listas usan item con atributo key y los nulos, null=\"true\"."},"example":"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response><error><status>404<\/status><message>Recurso no encontrado.<\/message><details><\/details><\/error><\/response>\n"}}},"NotAcceptable":{"description":"Formato no admitido en Accept o ?format=. Este error devuelve JSON.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ErrorResponse"},"example":{"error":{"status":406,"message":"Usa Accept: application\/json o application\/xml.","details":[]}}}}},"PayloadTooLarge":{"description":"El cuerpo JSON supera 256 KiB (262144 bytes).","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ErrorResponse"},"example":{"error":{"status":413,"message":"El cuerpo supera los 256 KiB.","details":[]}}},"application\/xml":{"schema":{"type":"string","description":"XML con ra\u00edz response; las listas usan item con atributo key y los nulos, null=\"true\"."},"example":"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response><error><status>413<\/status><message>El cuerpo supera los 256 KiB.<\/message><details><\/details><\/error><\/response>\n"}}},"UnsupportedMediaType":{"description":"El cuerpo debe enviarse con Content-Type: application\/json; no se admiten XML, formularios ni multipart.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ErrorResponse"},"example":{"error":{"status":415,"message":"Env\u00eda el cuerpo con Content-Type: application\/json.","details":[]}}},"application\/xml":{"schema":{"type":"string","description":"XML con ra\u00edz response; las listas usan item con atributo key y los nulos, null=\"true\"."},"example":"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response><error><status>415<\/status><message>Env\u00eda el cuerpo con Content-Type: application\/json.<\/message><details><\/details><\/error><\/response>\n"}}},"UnprocessableEntity":{"description":"Valores enviados inv\u00e1lidos, campos desconocidos, l\u00edmites documentales o condiciones de emisi\u00f3n. La ausencia de requisitos de emisi\u00f3n produce 201 draft, no 422. error.details usa rutas p\u00fablicas y la clave document para l\u00edmites.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ErrorResponse"},"example":{"error":{"status":422,"message":"Hay campos que necesitan corregirse.","details":{"vehicle.plate":["La matr\u00edcula no tiene un formato v\u00e1lido."],"carrier.taxId":["La identificaci\u00f3n fiscal no es v\u00e1lida."],"deliveries.0.weightKg":["El peso debe ser mayor que cero."]}}}},"application\/xml":{"schema":{"type":"string","description":"XML con ra\u00edz response; las listas usan item con atributo key y los nulos, null=\"true\"."},"example":"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response><error><status>422<\/status><message>Hay campos que necesitan corregirse.<\/message><details><item key=\"vehicle.plate\"><item key=\"0\">La matr\u00edcula no tiene un formato v\u00e1lido.<\/item><\/item><item key=\"carrier.taxId\"><item key=\"0\">La identificaci\u00f3n fiscal no es v\u00e1lida.<\/item><\/item><item key=\"deliveries.0.weightKg\"><item key=\"0\">El peso debe ser mayor que cero.<\/item><\/item><\/details><\/error><\/response>\n"}}},"TooManyRequests":{"description":"L\u00edmite compartido de 30 peticiones\/minuto por cuenta y entorno, o 120\/minuto por IP. Respeta Retry-After.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ErrorResponse"},"example":{"error":{"status":429,"message":"Too Many Attempts.","details":[]}}},"application\/xml":{"schema":{"type":"string","description":"XML con ra\u00edz response; las listas usan item con atributo key y los nulos, null=\"true\"."},"example":"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response><error><status>429<\/status><message>Too Many Attempts.<\/message><details><\/details><\/error><\/response>\n"}},"headers":{"X-RateLimit-Limit":{"$ref":"#\/components\/headers\/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#\/components\/headers\/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#\/components\/headers\/RateLimitReset"},"Retry-After":{"$ref":"#\/components\/headers\/RetryAfter"}}},"InternalServerError":{"description":"Error interno. Reintenta con la misma Idempotency-Key si la enviaste; sin clave, comprueba antes en el panel si el documento lleg\u00f3 a guardarse o emitirse.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ErrorResponse"},"example":{"error":{"status":500,"message":"No se ha podido generar el documento. Contacta con soporte.","details":[]}}},"application\/xml":{"schema":{"type":"string","description":"XML con ra\u00edz response; las listas usan item con atributo key y los nulos, null=\"true\"."},"example":"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response><error><status>500<\/status><message>No se ha podido generar el documento. Contacta con soporte.<\/message><details><\/details><\/error><\/response>\n"}}}}}}