{ "swagger": "2.0", "info": { "title": "DeCAred", "version": "1.3.0", "description": "API de integraciones de DeCAred, incluida en el plan Documentos ilimitados + carta de porte. Consulta documentos y PDF, prepara y modifica borradores y mantiene la agenda. La version 1.3 incorpora seguimiento privado y operaciones de oficina en dos pasos: propuesta con resumen y confirmacion explicita vinculada a su revision. Las claves anteriores conservan solo sus permisos anteriores. Emitir y corregir usa los servicios de DeCAred y puede planificar entregas reales al conductor.", "contact": { "name": "DeCAred · AYKENET", "email": "info@decared.com", "url": "https://decared.com" } }, "host": "decared.com", "basePath": "/api/v1", "schemes": [ "https" ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "paths": { "/me": { "get": { "operationId": "GetCompany", "summary": "Empresa de la conexión", "description": "Empresa y permisos de la clave", "responses": { "200": { "description": "OK", "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "company": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "nif": { "type": "string" } } }, "key": { "type": "object", "properties": { "name": { "type": "string" }, "abilities": { "type": "array", "items": { "type": "string", "enum": [ "read", "write", "documents:read", "drafts:read", "drafts:write", "counterparties:read", "counterparties:write", "vehicles:read", "vehicles:write", "drivers:read", "drivers:write", "webhooks:manage", "drafts:edit", "tracking:read", "attachments:read", "documents:issue", "documents:correct", "documents:close", "documents:annul", "documents:resend", "issues:report", "issues:manage", "messages:send" ] } } } } } } } } } } } }, "/documents": { "get": { "operationId": "ListDocuments", "summary": "Listar documentos emitidos", "description": "Para sondear cambios, usa updated_since con la fecha de la última consulta. Permiso especifico: documents:read. Las claves generales read/write conservan sus permisos anteriores.", "parameters": [ { "name": "reference", "in": "query", "required": false, "type": "string", "description": "Referencia exacta, por ejemplo DECA-2026-001095" }, { "name": "external_reference", "in": "query", "required": false, "type": "string", "description": "Referencia del pedido en tu sistema" }, { "name": "status", "in": "query", "required": false, "type": "string", "description": "status", "enum": [ "open", "closed", "annulled" ] }, { "name": "type", "in": "query", "required": false, "type": "string", "description": "type", "enum": [ "deca", "route_sheet", "carriage_letter" ] }, { "name": "updated_since", "in": "query", "required": false, "type": "string", "description": "updated_since", "format": "date-time" }, { "name": "page", "in": "query", "required": false, "type": "integer", "description": "page" }, { "name": "per_page", "in": "query", "required": false, "type": "integer", "description": "per_page" }, { "name": "pagination", "in": "query", "required": false, "type": "string", "description": "page (compatible) o cursor: orden ascendente por updated_at e id, con ventana temporal fija. No combinar cursor con page.", "enum": [ "page", "cursor" ] }, { "name": "cursor", "in": "query", "required": false, "type": "string", "description": "Token opaco next_cursor. Conservar los filtros originales. Ligado a empresa, recurso y filtros; caduca a las 24 horas." } ], "responses": { "200": { "description": "OK", "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/Document" } }, "meta": { "type": "object", "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "last_page": { "type": "integer" }, "has_more": { "type": "boolean" }, "next_cursor": { "type": "string", "x-nullable": true }, "sync_until": { "type": "string", "format": "date-time", "description": "Limite superior exclusivo del ciclo. Guardar solo tras agotar todas las paginas. Los cambios desde este instante se recuperan en el siguiente ciclo." } } } } } } } } }, "/documents/{id}": { "get": { "operationId": "GetDocument", "summary": "Obtener un documento con sus versiones", "description": "Detalle de un documento emitido.", "parameters": [ { "name": "id", "in": "path", "required": true, "type": "integer", "x-ms-summary": "Id" } ], "responses": { "200": { "description": "OK", "schema": { "type": "object", "properties": { "data": { "$ref": "#/definitions/Document" } } } } } } }, "/documents/{id}/versions/{number}/pdf": { "get": { "operationId": "DownloadPdf", "summary": "Descargar el PDF de una versión", "description": "Comprobado con su huella SHA-256.", "produces": [ "application/pdf" ], "parameters": [ { "name": "id", "in": "path", "required": true, "type": "integer", "x-ms-summary": "Id" }, { "name": "number", "in": "path", "required": true, "type": "integer", "x-ms-summary": "Versión" } ], "responses": { "200": { "description": "PDF", "schema": { "type": "string", "format": "binary" } } } } }, "/drafts": { "post": { "operationId": "CreateDraft", "summary": "Crear borrador de DeCA", "description": "Permiso drafts:write o write. Crea sin emitir. external_reference identifica un pedido por empresa: mismo contenido devuelve 200 e Idempotent-Replayed: true, incluso tras pasar la fecha del servicio. Contenido diferente devuelve 409; no modifica el borrador. Se normaliza el orden de campos, NIF/matriculas y peso numerico. Para evitar duplicados, enviar siempre external_reference. Las referencias previas sin huella conservan la compatibilidad.", "parameters": [ { "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/DraftInput" } } ], "responses": { "201": { "description": "Creado", "schema": { "type": "object", "properties": { "data": { "$ref": "#/definitions/Draft" } } } }, "200": { "description": "Ya existía", "schema": { "type": "object", "properties": { "data": { "$ref": "#/definitions/Draft" } } } } } }, "get": { "operationId": "ListDrafts", "summary": "Consultar borradores pendientes", "description": "Permiso drafts:read o read. Solo borradores de mercancias de la empresa. Admite external_reference, updated_since y paginacion por pagina o cursor.", "parameters": [ { "name": "external_reference", "in": "query", "required": false, "type": "string", "description": "external_reference" }, { "name": "updated_since", "in": "query", "required": false, "type": "string", "description": "Limite inferior inclusivo. Tras agotar el cursor, usar sync_until como updated_since del siguiente ciclo. Reconciliar por id y updated_at; no representa un historial de eliminaciones.", "format": "date-time" }, { "name": "per_page", "in": "query", "required": false, "type": "integer", "description": "per_page" }, { "name": "page", "in": "query", "required": false, "type": "integer", "description": "page" }, { "name": "pagination", "in": "query", "required": false, "type": "string", "description": "page (compatible) o cursor: orden ascendente por updated_at e id, con ventana temporal fija. No combinar cursor con page.", "enum": [ "page", "cursor" ] }, { "name": "cursor", "in": "query", "required": false, "type": "string", "description": "Token opaco next_cursor. Conservar los filtros originales. Ligado a empresa, recurso y filtros; caduca a las 24 horas." } ], "responses": { "200": { "description": "OK", "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/Draft" } }, "meta": { "type": "object", "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "last_page": { "type": "integer" }, "has_more": { "type": "boolean" }, "next_cursor": { "type": "string", "x-nullable": true }, "sync_until": { "type": "string", "format": "date-time", "description": "Limite superior exclusivo del ciclo. Guardar solo tras agotar todas las paginas. Los cambios desde este instante se recuperan en el siguiente ciclo." } } } } } } } } }, "/counterparties": { "post": { "operationId": "UpsertCounterparty", "summary": "Crear o actualizar empresa de la agenda", "description": "Crear o actualizar por NIF", "parameters": [ { "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/CounterpartyInput" } } ], "responses": { "201": { "description": "Creado" }, "200": { "description": "Actualizado" } } }, "get": { "operationId": "listCounterparties", "summary": "Empresas de la agenda", "description": " Permiso especifico: counterparties:read. Las claves generales read/write conservan sus permisos anteriores.", "parameters": [ { "name": "updated_since", "in": "query", "description": "Limite inferior inclusivo. Tras agotar el cursor, usar sync_until como updated_since del siguiente ciclo. Reconciliar por id y updated_at; no representa un historial de eliminaciones.", "type": "string", "format": "date-time" }, { "name": "per_page", "in": "query", "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, { "name": "pagination", "in": "query", "description": "page (compatible) o cursor: orden ascendente por updated_at e id, con ventana temporal fija. No combinar cursor con page.", "type": "string", "enum": [ "page", "cursor" ], "default": "page" }, { "name": "cursor", "in": "query", "description": "Token opaco next_cursor. Conservar los filtros originales. Ligado a empresa, recurso y filtros; caduca a las 24 horas.", "type": "string", "maxLength": 8192 } ], "responses": { "200": { "description": "Página", "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/Counterparty" } }, "meta": { "type": "object", "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "last_page": { "type": "integer" }, "has_more": { "type": "boolean" }, "next_cursor": { "type": "string", "x-nullable": true }, "sync_until": { "type": "string", "format": "date-time", "description": "Limite superior exclusivo del ciclo. Guardar solo tras agotar todas las paginas. Los cambios desde este instante se recuperan en el siguiente ciclo." } } } } }, "headers": { "X-Request-ID": { "type": "string", "format": "uuid" } } }, "401": { "description": "Clave ausente, no válida o revocada", "schema": { "$ref": "#/definitions/Error" }, "headers": { "X-Request-ID": { "type": "string", "format": "uuid" } } }, "403": { "description": "La empresa no tiene la API en su plan (o su suscripción no está al día), o la clave no tiene el permiso necesario", "schema": { "$ref": "#/definitions/Error" }, "headers": { "X-Request-ID": { "type": "string", "format": "uuid" } } }, "429": { "description": "Más de 120 peticiones por minuto con esta clave; espera los segundos de Retry-After", "schema": { "$ref": "#/definitions/Error" }, "headers": { "Retry-After": { "type": "integer" }, "X-Request-ID": { "type": "string", "format": "uuid" } } }, "422": { "description": "Datos no válidos", "schema": { "$ref": "#/definitions/Error" }, "headers": { "X-Request-ID": { "type": "string", "format": "uuid" } } } } } }, "/vehicles": { "post": { "operationId": "UpsertVehicle", "summary": "Crear o actualizar vehículo", "description": "Crear o actualizar por matrícula", "parameters": [ { "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/VehicleInput" } } ], "responses": { "201": { "description": "Creado" }, "200": { "description": "Actualizado" } } }, "get": { "operationId": "listVehicles", "summary": "Vehículos", "description": " Permiso especifico: vehicles:read. Las claves generales read/write conservan sus permisos anteriores.", "parameters": [ { "name": "updated_since", "in": "query", "description": "Limite inferior inclusivo. Tras agotar el cursor, usar sync_until como updated_since del siguiente ciclo. Reconciliar por id y updated_at; no representa un historial de eliminaciones.", "type": "string", "format": "date-time" }, { "name": "per_page", "in": "query", "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, { "name": "pagination", "in": "query", "description": "page (compatible) o cursor: orden ascendente por updated_at e id, con ventana temporal fija. No combinar cursor con page.", "type": "string", "enum": [ "page", "cursor" ], "default": "page" }, { "name": "cursor", "in": "query", "description": "Token opaco next_cursor. Conservar los filtros originales. Ligado a empresa, recurso y filtros; caduca a las 24 horas.", "type": "string", "maxLength": 8192 } ], "responses": { "200": { "description": "Página", "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/Vehicle" } }, "meta": { "type": "object", "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "last_page": { "type": "integer" }, "has_more": { "type": "boolean" }, "next_cursor": { "type": "string", "x-nullable": true }, "sync_until": { "type": "string", "format": "date-time", "description": "Limite superior exclusivo del ciclo. Guardar solo tras agotar todas las paginas. Los cambios desde este instante se recuperan en el siguiente ciclo." } } } } }, "headers": { "X-Request-ID": { "type": "string", "format": "uuid" } } }, "401": { "description": "Clave ausente, no válida o revocada", "schema": { "$ref": "#/definitions/Error" }, "headers": { "X-Request-ID": { "type": "string", "format": "uuid" } } }, "403": { "description": "La empresa no tiene la API en su plan (o su suscripción no está al día), o la clave no tiene el permiso necesario", "schema": { "$ref": "#/definitions/Error" }, "headers": { "X-Request-ID": { "type": "string", "format": "uuid" } } }, "429": { "description": "Más de 120 peticiones por minuto con esta clave; espera los segundos de Retry-After", "schema": { "$ref": "#/definitions/Error" }, "headers": { "Retry-After": { "type": "integer" }, "X-Request-ID": { "type": "string", "format": "uuid" } } }, "422": { "description": "Datos no válidos", "schema": { "$ref": "#/definitions/Error" }, "headers": { "X-Request-ID": { "type": "string", "format": "uuid" } } } } } }, "/drivers": { "post": { "operationId": "UpsertDriver", "summary": "Crear o actualizar conductor", "description": "Crear o actualizar por NIF", "parameters": [ { "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/DriverInput" } } ], "responses": { "201": { "description": "Creado" }, "200": { "description": "Actualizado" } } }, "get": { "operationId": "listDrivers", "summary": "Conductores", "description": " Permiso especifico: drivers:read. Las claves generales read/write conservan sus permisos anteriores.", "parameters": [ { "name": "updated_since", "in": "query", "description": "Limite inferior inclusivo. Tras agotar el cursor, usar sync_until como updated_since del siguiente ciclo. Reconciliar por id y updated_at; no representa un historial de eliminaciones.", "type": "string", "format": "date-time" }, { "name": "per_page", "in": "query", "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, { "name": "pagination", "in": "query", "description": "page (compatible) o cursor: orden ascendente por updated_at e id, con ventana temporal fija. No combinar cursor con page.", "type": "string", "enum": [ "page", "cursor" ], "default": "page" }, { "name": "cursor", "in": "query", "description": "Token opaco next_cursor. Conservar los filtros originales. Ligado a empresa, recurso y filtros; caduca a las 24 horas.", "type": "string", "maxLength": 8192 } ], "responses": { "200": { "description": "Página", "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/Driver" } }, "meta": { "type": "object", "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "last_page": { "type": "integer" }, "has_more": { "type": "boolean" }, "next_cursor": { "type": "string", "x-nullable": true }, "sync_until": { "type": "string", "format": "date-time", "description": "Limite superior exclusivo del ciclo. Guardar solo tras agotar todas las paginas. Los cambios desde este instante se recuperan en el siguiente ciclo." } } } } }, "headers": { "X-Request-ID": { "type": "string", "format": "uuid" } } }, "401": { "description": "Clave ausente, no válida o revocada", "schema": { "$ref": "#/definitions/Error" }, "headers": { "X-Request-ID": { "type": "string", "format": "uuid" } } }, "403": { "description": "La empresa no tiene la API en su plan (o su suscripción no está al día), o la clave no tiene el permiso necesario", "schema": { "$ref": "#/definitions/Error" }, "headers": { "X-Request-ID": { "type": "string", "format": "uuid" } } }, "429": { "description": "Más de 120 peticiones por minuto con esta clave; espera los segundos de Retry-After", "schema": { "$ref": "#/definitions/Error" }, "headers": { "Retry-After": { "type": "integer" }, "X-Request-ID": { "type": "string", "format": "uuid" } } }, "422": { "description": "Datos no válidos", "schema": { "$ref": "#/definitions/Error" }, "headers": { "X-Request-ID": { "type": "string", "format": "uuid" } } } } } }, "/webhooks": { "post": { "operationId": "WhenDocumentEvent", "summary": "Cuando ocurre un evento en un documento", "description": "Se dispara al emitir, corregir, cerrar o anular un documento, o cuando el conductor confirma o finaliza.", "x-ms-trigger": "single", "x-ms-trigger-hint": "Para verlo funcionar, emite un documento en DeCAred.", "parameters": [ { "name": "body", "in": "body", "required": true, "schema": { "type": "object", "required": [ "url", "event" ], "properties": { "url": { "type": "string", "x-ms-notification-url": true, "x-ms-visibility": "internal", "title": "URL de aviso" }, "event": { "type": "string", "title": "Evento", "enum": [ "document.issued", "document.corrected", "document.closed", "document.annulled", "document.receipt_confirmed", "document.service_finished" ], "x-ms-enum-values": [ { "value": "document.issued", "displayName": "Documento emitido" }, { "value": "document.corrected", "displayName": "Documento corregido (nueva versión)" }, { "value": "document.closed", "displayName": "Documento cerrado" }, { "value": "document.annulled", "displayName": "Documento anulado" }, { "value": "document.receipt_confirmed", "displayName": "El conductor confirma la recepción" }, { "value": "document.service_finished", "displayName": "El conductor comunica que ha terminado el servicio" } ] } } } } ], "responses": { "201": { "description": "Evento recibido", "schema": { "type": "object", "description": "Cuerpo de cada webhook. Cabeceras: DeCAred-Event, DeCAred-Delivery (id del evento) y DeCAred-Signature «t=,v1=», HMAC-SHA256 de \".\" con el secreto del destino. Entrega al menos una vez: deduplica por id. Responde 2xx en menos de 10 segundos.", "properties": { "id": { "type": "string", "format": "uuid" }, "event": { "type": "string", "enum": [ "document.issued", "document.corrected", "document.closed", "document.annulled", "document.receipt_confirmed", "document.service_finished", "ping" ] }, "created_at": { "type": "string", "format": "date-time" }, "company_id": { "type": "integer" }, "data": { "$ref": "#/definitions/Document" } } } } } }, "get": { "operationId": "listWebhooks", "summary": "Destinos de webhooks activos de la empresa", "description": " Permiso especifico: webhooks:manage. Las claves generales read/write conservan sus permisos anteriores.", "parameters": [], "responses": { "200": { "description": "Destinos", "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/WebhookSubscription" } } } }, "headers": { "X-Request-ID": { "type": "string", "format": "uuid" } } }, "401": { "description": "Clave ausente, no válida o revocada", "schema": { "$ref": "#/definitions/Error" }, "headers": { "X-Request-ID": { "type": "string", "format": "uuid" } } }, "403": { "description": "La empresa no tiene la API en su plan (o su suscripción no está al día), o la clave no tiene el permiso necesario", "schema": { "$ref": "#/definitions/Error" }, "headers": { "X-Request-ID": { "type": "string", "format": "uuid" } } }, "429": { "description": "Más de 120 peticiones por minuto con esta clave; espera los segundos de Retry-After", "schema": { "$ref": "#/definitions/Error" }, "headers": { "Retry-After": { "type": "integer" }, "X-Request-ID": { "type": "string", "format": "uuid" } } } } } }, "/webhooks/{id}": { "delete": { "operationId": "DeleteSubscription", "summary": "Dar de baja la suscripción", "x-ms-visibility": "internal", "parameters": [ { "name": "id", "in": "path", "required": true, "type": "integer", "x-ms-summary": "Id" } ], "responses": { "204": { "description": "Eliminada" } } } }, "/drafts/{id}": { "get": { "operationId": "getDraft", "summary": "Estado de un borrador creado por la API", "description": " Permiso especifico: drafts:read. Las claves generales read/write conservan sus permisos anteriores.", "parameters": [ { "name": "id", "in": "path", "required": true, "type": "integer" } ], "responses": { "200": { "description": "Borrador", "schema": { "type": "object", "properties": { "data": { "$ref": "#/definitions/Draft" } } }, "headers": { "X-Request-ID": { "type": "string", "format": "uuid" } } }, "404": { "description": "No existe en esta empresa", "schema": { "$ref": "#/definitions/Error" }, "headers": { "X-Request-ID": { "type": "string", "format": "uuid" } } }, "401": { "description": "Clave ausente, no válida o revocada", "schema": { "$ref": "#/definitions/Error" }, "headers": { "X-Request-ID": { "type": "string", "format": "uuid" } } }, "403": { "description": "La empresa no tiene la API en su plan (o su suscripción no está al día), o la clave no tiene el permiso necesario", "schema": { "$ref": "#/definitions/Error" }, "headers": { "X-Request-ID": { "type": "string", "format": "uuid" } } }, "429": { "description": "Más de 120 peticiones por minuto con esta clave; espera los segundos de Retry-After", "schema": { "$ref": "#/definitions/Error" }, "headers": { "Retry-After": { "type": "integer" }, "X-Request-ID": { "type": "string", "format": "uuid" } } } } }, "patch": { "operationId": "updateDraft", "summary": "Modificar un borrador sin emitir", "description": "Requiere drafts:edit y acceso vigente del creador de la clave como gestor. revision es obligatoria; un cambio concurrente devuelve 409. data usa los nombres nativos de document_data; shipments reemplaza toda la lista.", "parameters": [ { "name": "id", "in": "path", "required": true, "type": "integer" }, { "name": "body", "in": "body", "required": true, "schema": { "type": "object", "required": [ "revision", "data" ], "properties": { "revision": { "type": "integer", "minimum": 0 }, "data": { "$ref": "#/definitions/NativeDocumentData" } } } } ], "responses": { "200": { "description": "Modificar un borrador sin emitir", "schema": { "type": "object", "properties": { "data": { "$ref": "#/definitions/Draft" } } }, "headers": { "X-Request-ID": { "type": "string", "format": "uuid" } } }, "401": { "description": "Clave ausente, no válida o revocada", "schema": { "$ref": "#/definitions/Error" }, "headers": { "X-Request-ID": { "type": "string", "format": "uuid" } } }, "403": { "description": "La empresa no tiene la API en su plan (o su suscripción no está al día), o la clave no tiene el permiso necesario", "schema": { "$ref": "#/definitions/Error" }, "headers": { "X-Request-ID": { "type": "string", "format": "uuid" } } }, "404": { "description": "No existe en esta empresa", "schema": { "$ref": "#/definitions/Error" }, "headers": { "X-Request-ID": { "type": "string", "format": "uuid" } } }, "409": { "description": "El documento o la incidencia han cambiado, propuesta caducada, estado incompatible u operacion en curso/incierta. Consultar el estado y conciliar; no repetir automaticamente.", "schema": { "$ref": "#/definitions/Error" } }, "422": { "description": "Datos no válidos", "schema": { "$ref": "#/definitions/Error" }, "headers": { "X-Request-ID": { "type": "string", "format": "uuid" } } }, "429": { "description": "Más de 120 peticiones por minuto con esta clave; espera los segundos de Retry-After", "schema": { "$ref": "#/definitions/Error" }, "headers": { "Retry-After": { "type": "integer" }, "X-Request-ID": { "type": "string", "format": "uuid" } } } } } }, "/documents/{id}/actions": { "post": { "operationId": "prepareOperation", "summary": "Preparar una operacion de oficina", "description": "Solo DeCA independientes de mercancias. No ejecuta el efecto: guarda una propuesta cifrada durante 15 minutos. Requiere el permiso especifico de action y un gestor vigente. data solo se admite para correct; issue usa el borrador guardado. reason obligatorio en correct/annul; body en message/report_issue/resolve_issue; issue_id en resolve_issue. close exige finalizacion del conductor. Los campos de permiso no se heredan de read/write. Limite adicional: 30 peticiones de preparacion por minuto por clave, con Retry-After al superarlo.", "parameters": [ { "name": "id", "in": "path", "required": true, "type": "integer" }, { "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/PrepareOperation" } } ], "responses": { "201": { "description": "Preparar una operacion de oficina", "schema": { "type": "object", "properties": { "data": { "$ref": "#/definitions/ApiOperation" } } }, "headers": { "X-Request-ID": { "type": "string", "format": "uuid" } } }, "401": { "description": "Clave ausente, no válida o revocada", "schema": { "$ref": "#/definitions/Error" }, "headers": { "X-Request-ID": { "type": "string", "format": "uuid" } } }, "403": { "description": "La empresa no tiene la API en su plan (o su suscripción no está al día), o la clave no tiene el permiso necesario", "schema": { "$ref": "#/definitions/Error" }, "headers": { "X-Request-ID": { "type": "string", "format": "uuid" } } }, "404": { "description": "No existe en esta empresa", "schema": { "$ref": "#/definitions/Error" }, "headers": { "X-Request-ID": { "type": "string", "format": "uuid" } } }, "409": { "description": "El documento o la incidencia han cambiado, propuesta caducada, estado incompatible u operacion en curso/incierta. Consultar el estado y conciliar; no repetir automaticamente.", "schema": { "$ref": "#/definitions/Error" } }, "422": { "description": "Datos no válidos", "schema": { "$ref": "#/definitions/Error" }, "headers": { "X-Request-ID": { "type": "string", "format": "uuid" } } }, "429": { "description": "Más de 120 peticiones por minuto con esta clave; espera los segundos de Retry-After", "schema": { "$ref": "#/definitions/Error" }, "headers": { "Retry-After": { "type": "integer" }, "X-Request-ID": { "type": "string", "format": "uuid" } } } } } }, "/operations/{operation}": { "get": { "operationId": "getOperation", "summary": "Consultar el resultado de una operacion", "description": "Solo la misma empresa, clave y creador con permisos vigentes. No devuelve el token de confirmacion.", "parameters": [ { "name": "operation", "in": "path", "required": true, "type": "string", "format": "uuid" } ], "responses": { "200": { "description": "Consultar el resultado de una operacion", "schema": { "type": "object", "properties": { "data": { "$ref": "#/definitions/ApiOperation" } } }, "headers": { "X-Request-ID": { "type": "string", "format": "uuid" } } }, "401": { "description": "Clave ausente, no válida o revocada", "schema": { "$ref": "#/definitions/Error" }, "headers": { "X-Request-ID": { "type": "string", "format": "uuid" } } }, "403": { "description": "La empresa no tiene la API en su plan (o su suscripción no está al día), o la clave no tiene el permiso necesario", "schema": { "$ref": "#/definitions/Error" }, "headers": { "X-Request-ID": { "type": "string", "format": "uuid" } } }, "404": { "description": "No existe en esta empresa", "schema": { "$ref": "#/definitions/Error" }, "headers": { "X-Request-ID": { "type": "string", "format": "uuid" } } }, "409": { "description": "El documento o la incidencia han cambiado, propuesta caducada, estado incompatible u operacion en curso/incierta. Consultar el estado y conciliar; no repetir automaticamente.", "schema": { "$ref": "#/definitions/Error" } }, "422": { "description": "Datos no válidos", "schema": { "$ref": "#/definitions/Error" }, "headers": { "X-Request-ID": { "type": "string", "format": "uuid" } } }, "429": { "description": "Más de 120 peticiones por minuto con esta clave; espera los segundos de Retry-After", "schema": { "$ref": "#/definitions/Error" }, "headers": { "Retry-After": { "type": "integer" }, "X-Request-ID": { "type": "string", "format": "uuid" } } } } } }, "/operations/{operation}/confirm": { "post": { "operationId": "confirmOperation", "summary": "Confirmar exactamente la propuesta preparada", "description": "Misma clave y token. confirmed declara la autorizacion expresa del resumen. Se vuelve a comprobar revision, version, incidencia y permisos. Repetir una operacion completada devuelve el resultado persistido; executing/uncertain nunca se reejecutan automaticamente. No se aceptan nuevos datos para alterar la propuesta. Desactive reintentos automáticos. Ante timeout consulte el estado de la misma operación antes de continuar.", "parameters": [ { "name": "operation", "in": "path", "required": true, "type": "string", "format": "uuid" }, { "name": "body", "in": "body", "required": true, "schema": { "type": "object", "required": [ "confirmed", "confirmation_token" ], "properties": { "confirmed": { "type": "boolean", "enum": [ true ] }, "confirmation_token": { "type": "string", "minLength": 48, "maxLength": 48 } } } } ], "responses": { "200": { "description": "Confirmar exactamente la propuesta preparada", "schema": { "type": "object", "properties": { "data": { "$ref": "#/definitions/ApiOperation" } } }, "headers": { "X-Request-ID": { "type": "string", "format": "uuid" } } }, "401": { "description": "Clave ausente, no válida o revocada", "schema": { "$ref": "#/definitions/Error" }, "headers": { "X-Request-ID": { "type": "string", "format": "uuid" } } }, "403": { "description": "La empresa no tiene la API en su plan (o su suscripción no está al día), o la clave no tiene el permiso necesario", "schema": { "$ref": "#/definitions/Error" }, "headers": { "X-Request-ID": { "type": "string", "format": "uuid" } } }, "404": { "description": "No existe en esta empresa", "schema": { "$ref": "#/definitions/Error" }, "headers": { "X-Request-ID": { "type": "string", "format": "uuid" } } }, "409": { "description": "El documento o la incidencia han cambiado, propuesta caducada, estado incompatible u operacion en curso/incierta. Consultar el estado y conciliar; no repetir automaticamente.", "schema": { "$ref": "#/definitions/Error" } }, "422": { "description": "Datos no válidos", "schema": { "$ref": "#/definitions/Error" }, "headers": { "X-Request-ID": { "type": "string", "format": "uuid" } } }, "429": { "description": "Más de 120 peticiones por minuto con esta clave; espera los segundos de Retry-After", "schema": { "$ref": "#/definitions/Error" }, "headers": { "Retry-After": { "type": "integer" }, "X-Request-ID": { "type": "string", "format": "uuid" } } } } } }, "/documents/{id}/tracking": { "get": { "operationId": "getTracking", "summary": "Consultar el estado de seguimiento", "description": "Incluye datos internos. Requiere tracking:read y acceso vigente del creador de la clave. Aceptacion por el proveedor no acredita entrega ni lectura; finalizacion no es firma ni cierre.", "parameters": [ { "name": "id", "in": "path", "required": true, "type": "integer" } ], "responses": { "200": { "description": "Consultar el estado de seguimiento", "schema": { "type": "object", "properties": { "data": { "$ref": "#/definitions/TrackingSummary" } } }, "headers": { "X-Request-ID": { "type": "string", "format": "uuid" } } }, "401": { "description": "Clave ausente, no válida o revocada", "schema": { "$ref": "#/definitions/Error" }, "headers": { "X-Request-ID": { "type": "string", "format": "uuid" } } }, "403": { "description": "La empresa no tiene la API en su plan (o su suscripción no está al día), o la clave no tiene el permiso necesario", "schema": { "$ref": "#/definitions/Error" }, "headers": { "X-Request-ID": { "type": "string", "format": "uuid" } } }, "404": { "description": "No existe en esta empresa", "schema": { "$ref": "#/definitions/Error" }, "headers": { "X-Request-ID": { "type": "string", "format": "uuid" } } }, "409": { "description": "El documento o la incidencia han cambiado, propuesta caducada, estado incompatible u operacion en curso/incierta. Consultar el estado y conciliar; no repetir automaticamente.", "schema": { "$ref": "#/definitions/Error" } }, "422": { "description": "Datos no válidos", "schema": { "$ref": "#/definitions/Error" }, "headers": { "X-Request-ID": { "type": "string", "format": "uuid" } } }, "429": { "description": "Más de 120 peticiones por minuto con esta clave; espera los segundos de Retry-After", "schema": { "$ref": "#/definitions/Error" }, "headers": { "Retry-After": { "type": "integer" }, "X-Request-ID": { "type": "string", "format": "uuid" } } } } } }, "/documents/{id}/tracking/deliveries": { "get": { "operationId": "listTrackingDeliveries", "summary": "Consultar deliveries del seguimiento", "description": "Datos de esta empresa y documento, ordenados por id descendente y paginados (50, maximo 100). Incluye notas internas. No devuelve cuerpos tecnicos, chat_id ni contenido binario. Los cambios de incidencias/mensajes no tienen nuevos webhooks en esta version.", "parameters": [ { "name": "id", "in": "path", "required": true, "type": "integer" }, { "name": "page", "in": "query", "type": "integer", "minimum": 1, "default": 1 }, { "name": "per_page", "in": "query", "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } ], "responses": { "200": { "description": "Pagina de deliveries", "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/DeliveryRecord" } }, "meta": { "$ref": "#/definitions/Page" } } }, "headers": { "X-Request-ID": { "type": "string", "format": "uuid" } } }, "401": { "description": "Clave ausente, no válida o revocada", "schema": { "$ref": "#/definitions/Error" }, "headers": { "X-Request-ID": { "type": "string", "format": "uuid" } } }, "403": { "description": "La empresa no tiene la API en su plan (o su suscripción no está al día), o la clave no tiene el permiso necesario", "schema": { "$ref": "#/definitions/Error" }, "headers": { "X-Request-ID": { "type": "string", "format": "uuid" } } }, "404": { "description": "No existe en esta empresa", "schema": { "$ref": "#/definitions/Error" }, "headers": { "X-Request-ID": { "type": "string", "format": "uuid" } } }, "409": { "description": "El documento o la incidencia han cambiado, propuesta caducada, estado incompatible u operacion en curso/incierta. Consultar el estado y conciliar; no repetir automaticamente.", "schema": { "$ref": "#/definitions/Error" } }, "422": { "description": "Datos no válidos", "schema": { "$ref": "#/definitions/Error" }, "headers": { "X-Request-ID": { "type": "string", "format": "uuid" } } }, "429": { "description": "Más de 120 peticiones por minuto con esta clave; espera los segundos de Retry-After", "schema": { "$ref": "#/definitions/Error" }, "headers": { "Retry-After": { "type": "integer" }, "X-Request-ID": { "type": "string", "format": "uuid" } } } } } }, "/documents/{id}/tracking/interactions": { "get": { "operationId": "listTrackingInteractions", "summary": "Consultar interactions del seguimiento", "description": "Datos de esta empresa y documento, ordenados por id descendente y paginados (50, maximo 100). Incluye notas internas. No devuelve cuerpos tecnicos, chat_id ni contenido binario. Los cambios de incidencias/mensajes no tienen nuevos webhooks en esta version.", "parameters": [ { "name": "id", "in": "path", "required": true, "type": "integer" }, { "name": "page", "in": "query", "type": "integer", "minimum": 1, "default": 1 }, { "name": "per_page", "in": "query", "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } ], "responses": { "200": { "description": "Pagina de interactions", "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/InteractionRecord" } }, "meta": { "$ref": "#/definitions/Page" } } }, "headers": { "X-Request-ID": { "type": "string", "format": "uuid" } } }, "401": { "description": "Clave ausente, no válida o revocada", "schema": { "$ref": "#/definitions/Error" }, "headers": { "X-Request-ID": { "type": "string", "format": "uuid" } } }, "403": { "description": "La empresa no tiene la API en su plan (o su suscripción no está al día), o la clave no tiene el permiso necesario", "schema": { "$ref": "#/definitions/Error" }, "headers": { "X-Request-ID": { "type": "string", "format": "uuid" } } }, "404": { "description": "No existe en esta empresa", "schema": { "$ref": "#/definitions/Error" }, "headers": { "X-Request-ID": { "type": "string", "format": "uuid" } } }, "409": { "description": "El documento o la incidencia han cambiado, propuesta caducada, estado incompatible u operacion en curso/incierta. Consultar el estado y conciliar; no repetir automaticamente.", "schema": { "$ref": "#/definitions/Error" } }, "422": { "description": "Datos no válidos", "schema": { "$ref": "#/definitions/Error" }, "headers": { "X-Request-ID": { "type": "string", "format": "uuid" } } }, "429": { "description": "Más de 120 peticiones por minuto con esta clave; espera los segundos de Retry-After", "schema": { "$ref": "#/definitions/Error" }, "headers": { "Retry-After": { "type": "integer" }, "X-Request-ID": { "type": "string", "format": "uuid" } } } } } }, "/documents/{id}/tracking/issues": { "get": { "operationId": "listTrackingIssues", "summary": "Consultar issues del seguimiento", "description": "Datos de esta empresa y documento, ordenados por id descendente y paginados (50, maximo 100). Incluye notas internas. No devuelve cuerpos tecnicos, chat_id ni contenido binario. Los cambios de incidencias/mensajes no tienen nuevos webhooks en esta version.", "parameters": [ { "name": "id", "in": "path", "required": true, "type": "integer" }, { "name": "page", "in": "query", "type": "integer", "minimum": 1, "default": 1 }, { "name": "per_page", "in": "query", "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } ], "responses": { "200": { "description": "Pagina de issues", "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/IssueRecord" } }, "meta": { "$ref": "#/definitions/Page" } } }, "headers": { "X-Request-ID": { "type": "string", "format": "uuid" } } }, "401": { "description": "Clave ausente, no válida o revocada", "schema": { "$ref": "#/definitions/Error" }, "headers": { "X-Request-ID": { "type": "string", "format": "uuid" } } }, "403": { "description": "La empresa no tiene la API en su plan (o su suscripción no está al día), o la clave no tiene el permiso necesario", "schema": { "$ref": "#/definitions/Error" }, "headers": { "X-Request-ID": { "type": "string", "format": "uuid" } } }, "404": { "description": "No existe en esta empresa", "schema": { "$ref": "#/definitions/Error" }, "headers": { "X-Request-ID": { "type": "string", "format": "uuid" } } }, "409": { "description": "El documento o la incidencia han cambiado, propuesta caducada, estado incompatible u operacion en curso/incierta. Consultar el estado y conciliar; no repetir automaticamente.", "schema": { "$ref": "#/definitions/Error" } }, "422": { "description": "Datos no válidos", "schema": { "$ref": "#/definitions/Error" }, "headers": { "X-Request-ID": { "type": "string", "format": "uuid" } } }, "429": { "description": "Más de 120 peticiones por minuto con esta clave; espera los segundos de Retry-After", "schema": { "$ref": "#/definitions/Error" }, "headers": { "Retry-After": { "type": "integer" }, "X-Request-ID": { "type": "string", "format": "uuid" } } } } } }, "/documents/{id}/tracking/issue_events": { "get": { "operationId": "listTrackingIssueEvents", "summary": "Consultar issue_events del seguimiento", "description": "Datos de esta empresa y documento, ordenados por id descendente y paginados (50, maximo 100). Incluye notas internas. No devuelve cuerpos tecnicos, chat_id ni contenido binario. Los cambios de incidencias/mensajes no tienen nuevos webhooks en esta version.", "parameters": [ { "name": "id", "in": "path", "required": true, "type": "integer" }, { "name": "page", "in": "query", "type": "integer", "minimum": 1, "default": 1 }, { "name": "per_page", "in": "query", "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } ], "responses": { "200": { "description": "Pagina de issue_events", "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/IssueEventRecord" } }, "meta": { "$ref": "#/definitions/Page" } } }, "headers": { "X-Request-ID": { "type": "string", "format": "uuid" } } }, "401": { "description": "Clave ausente, no válida o revocada", "schema": { "$ref": "#/definitions/Error" }, "headers": { "X-Request-ID": { "type": "string", "format": "uuid" } } }, "403": { "description": "La empresa no tiene la API en su plan (o su suscripción no está al día), o la clave no tiene el permiso necesario", "schema": { "$ref": "#/definitions/Error" }, "headers": { "X-Request-ID": { "type": "string", "format": "uuid" } } }, "404": { "description": "No existe en esta empresa", "schema": { "$ref": "#/definitions/Error" }, "headers": { "X-Request-ID": { "type": "string", "format": "uuid" } } }, "409": { "description": "El documento o la incidencia han cambiado, propuesta caducada, estado incompatible u operacion en curso/incierta. Consultar el estado y conciliar; no repetir automaticamente.", "schema": { "$ref": "#/definitions/Error" } }, "422": { "description": "Datos no válidos", "schema": { "$ref": "#/definitions/Error" }, "headers": { "X-Request-ID": { "type": "string", "format": "uuid" } } }, "429": { "description": "Más de 120 peticiones por minuto con esta clave; espera los segundos de Retry-After", "schema": { "$ref": "#/definitions/Error" }, "headers": { "Retry-After": { "type": "integer" }, "X-Request-ID": { "type": "string", "format": "uuid" } } } } } }, "/documents/{id}/tracking/messages": { "get": { "operationId": "listTrackingMessages", "summary": "Consultar messages del seguimiento", "description": "Datos de esta empresa y documento, ordenados por id descendente y paginados (50, maximo 100). Incluye notas internas. No devuelve cuerpos tecnicos, chat_id ni contenido binario. Los cambios de incidencias/mensajes no tienen nuevos webhooks en esta version.", "parameters": [ { "name": "id", "in": "path", "required": true, "type": "integer" }, { "name": "page", "in": "query", "type": "integer", "minimum": 1, "default": 1 }, { "name": "per_page", "in": "query", "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } ], "responses": { "200": { "description": "Pagina de messages", "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/MessageRecord" } }, "meta": { "$ref": "#/definitions/Page" } } }, "headers": { "X-Request-ID": { "type": "string", "format": "uuid" } } }, "401": { "description": "Clave ausente, no válida o revocada", "schema": { "$ref": "#/definitions/Error" }, "headers": { "X-Request-ID": { "type": "string", "format": "uuid" } } }, "403": { "description": "La empresa no tiene la API en su plan (o su suscripción no está al día), o la clave no tiene el permiso necesario", "schema": { "$ref": "#/definitions/Error" }, "headers": { "X-Request-ID": { "type": "string", "format": "uuid" } } }, "404": { "description": "No existe en esta empresa", "schema": { "$ref": "#/definitions/Error" }, "headers": { "X-Request-ID": { "type": "string", "format": "uuid" } } }, "409": { "description": "El documento o la incidencia han cambiado, propuesta caducada, estado incompatible u operacion en curso/incierta. Consultar el estado y conciliar; no repetir automaticamente.", "schema": { "$ref": "#/definitions/Error" } }, "422": { "description": "Datos no válidos", "schema": { "$ref": "#/definitions/Error" }, "headers": { "X-Request-ID": { "type": "string", "format": "uuid" } } }, "429": { "description": "Más de 120 peticiones por minuto con esta clave; espera los segundos de Retry-After", "schema": { "$ref": "#/definitions/Error" }, "headers": { "Retry-After": { "type": "integer" }, "X-Request-ID": { "type": "string", "format": "uuid" } } } } } }, "/documents/{id}/tracking/attachments": { "get": { "operationId": "listTrackingAttachments", "summary": "Consultar attachments del seguimiento", "description": "Datos de esta empresa y documento, ordenados por id descendente y paginados (50, maximo 100). Incluye notas internas. No devuelve cuerpos tecnicos, chat_id ni contenido binario. Los cambios de incidencias/mensajes no tienen nuevos webhooks en esta version.", "parameters": [ { "name": "id", "in": "path", "required": true, "type": "integer" }, { "name": "page", "in": "query", "type": "integer", "minimum": 1, "default": 1 }, { "name": "per_page", "in": "query", "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } ], "responses": { "200": { "description": "Pagina de attachments", "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/AttachmentRecord" } }, "meta": { "$ref": "#/definitions/Page" } } }, "headers": { "X-Request-ID": { "type": "string", "format": "uuid" } } }, "401": { "description": "Clave ausente, no válida o revocada", "schema": { "$ref": "#/definitions/Error" }, "headers": { "X-Request-ID": { "type": "string", "format": "uuid" } } }, "403": { "description": "La empresa no tiene la API en su plan (o su suscripción no está al día), o la clave no tiene el permiso necesario", "schema": { "$ref": "#/definitions/Error" }, "headers": { "X-Request-ID": { "type": "string", "format": "uuid" } } }, "404": { "description": "No existe en esta empresa", "schema": { "$ref": "#/definitions/Error" }, "headers": { "X-Request-ID": { "type": "string", "format": "uuid" } } }, "409": { "description": "El documento o la incidencia han cambiado, propuesta caducada, estado incompatible u operacion en curso/incierta. Consultar el estado y conciliar; no repetir automaticamente.", "schema": { "$ref": "#/definitions/Error" } }, "422": { "description": "Datos no válidos", "schema": { "$ref": "#/definitions/Error" }, "headers": { "X-Request-ID": { "type": "string", "format": "uuid" } } }, "429": { "description": "Más de 120 peticiones por minuto con esta clave; espera los segundos de Retry-After", "schema": { "$ref": "#/definitions/Error" }, "headers": { "Retry-After": { "type": "integer" }, "X-Request-ID": { "type": "string", "format": "uuid" } } } } } }, "/documents/{id}/attachments/{attachment}": { "get": { "operationId": "downloadTrackingAttachment", "summary": "Descargar un adjunto privado", "description": "Requiere attachments:read y acceso vigente. Comprueba empresa, documento y SHA-256, con descarga sin cache.", "parameters": [ { "name": "id", "in": "path", "required": true, "type": "integer" }, { "name": "attachment", "in": "path", "required": true, "type": "integer", "minimum": 1 } ], "responses": { "200": { "description": "JPEG, PNG o PDF original", "schema": { "type": "file" } }, "401": { "description": "Clave ausente, no válida o revocada", "schema": { "$ref": "#/definitions/Error" }, "headers": { "X-Request-ID": { "type": "string", "format": "uuid" } } }, "403": { "description": "La empresa no tiene la API en su plan (o su suscripción no está al día), o la clave no tiene el permiso necesario", "schema": { "$ref": "#/definitions/Error" }, "headers": { "X-Request-ID": { "type": "string", "format": "uuid" } } }, "404": { "description": "No existe en esta empresa", "schema": { "$ref": "#/definitions/Error" }, "headers": { "X-Request-ID": { "type": "string", "format": "uuid" } } }, "409": { "description": "El documento o la incidencia han cambiado, propuesta caducada, estado incompatible u operacion en curso/incierta. Consultar el estado y conciliar; no repetir automaticamente.", "schema": { "$ref": "#/definitions/Error" } }, "422": { "description": "Datos no válidos", "schema": { "$ref": "#/definitions/Error" }, "headers": { "X-Request-ID": { "type": "string", "format": "uuid" } } }, "429": { "description": "Más de 120 peticiones por minuto con esta clave; espera los segundos de Retry-After", "schema": { "$ref": "#/definitions/Error" }, "headers": { "Retry-After": { "type": "integer" }, "X-Request-ID": { "type": "string", "format": "uuid" } } } }, "produces": [ "application/octet-stream" ] } } }, "definitions": { "Page": { "type": "object", "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "last_page": { "type": "integer" } }, "required": [ "page", "per_page", "total", "last_page" ] }, "Version": { "type": "object", "properties": { "number": { "type": "integer" }, "issued_at": { "type": "string", "format": "date-time" }, "sha256": { "type": "string" }, "public_url": { "type": "string", "format": "uri", "description": "Enlace del QR de esa versión" }, "pdf_url": { "type": "string", "format": "uri" }, "reason": { "type": "string", "x-nullable": true } } }, "Party": { "type": "object", "x-nullable": true, "properties": { "name": { "type": "string" }, "nif": { "type": "string" }, "address": { "type": "string" } } }, "Shipment": { "type": "object", "properties": { "shipment_reference": { "type": "string" }, "carriage_reference": { "type": "string", "x-nullable": true }, "origin": { "type": "string" }, "origin_name": { "type": "string", "x-nullable": true }, "destination": { "type": "string" }, "destination_name": { "type": "string", "x-nullable": true }, "goods": { "type": "string" }, "weight": { "type": "string", "x-nullable": true, "description": "Peso bruto en kg" }, "alternative": { "type": "string", "x-nullable": true, "description": "Otra medida si no hay peso" }, "packages": { "type": "string", "x-nullable": true }, "packaging": { "type": "string", "x-nullable": true }, "adr": { "type": "string", "x-nullable": true }, "recipient": { "type": "string", "x-nullable": true }, "observations": { "type": "string", "x-nullable": true } } }, "Document": { "type": "object", "description": "Datos de la versión vigente, tomados de su instantánea inmutable.", "properties": { "id": { "type": "integer" }, "reference": { "type": "string", "example": "DECA-2026-001095" }, "type": { "type": "string", "enum": [ "deca", "route_sheet", "carriage_letter" ] }, "status": { "type": "string", "enum": [ "open", "closed", "annulled" ] }, "external_reference": { "type": "string", "x-nullable": true }, "accompanies_carriage_letter_id": { "type": "integer", "x-nullable": true }, "document_date": { "type": "string", "format": "date" }, "service_date": { "type": "string", "format": "date" }, "first_issued_at": { "type": "string", "format": "date-time" }, "closed_at": { "type": "string", "format": "date-time", "x-nullable": true }, "annulled_at": { "type": "string", "format": "date-time", "x-nullable": true }, "annulment_reason": { "type": "string", "x-nullable": true }, "updated_at": { "type": "string", "format": "date-time" }, "current_version": { "$ref": "#/definitions/Version" }, "versions": { "type": "array", "items": { "$ref": "#/definitions/Version" }, "description": "Solo en el detalle" }, "company": { "$ref": "#/definitions/Party" }, "shipper": { "$ref": "#/definitions/Party" }, "carrier": { "$ref": "#/definitions/Party" }, "vehicle": { "type": "object", "x-nullable": true, "properties": { "plate": { "type": "string" }, "trailer": { "type": "string", "x-nullable": true } } }, "driver": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "shipments": { "type": "array", "items": { "$ref": "#/definitions/Shipment" } }, "revision": { "type": "integer", "minimum": 0 } } }, "DraftShipmentInput": { "type": "object", "required": [ "origin", "destination" ], "properties": { "origin": { "type": "string", "maxLength": 400 }, "origin_name": { "type": "string" }, "destination": { "type": "string", "maxLength": 400 }, "destination_name": { "type": "string" }, "goods": { "type": "string" }, "weight": { "type": "number", "description": "Peso bruto en kg" }, "alternative": { "type": "string" }, "packages": { "type": "string" }, "packaging": { "type": "string" }, "recipient": { "type": "string" }, "observations": { "type": "string" }, "adr": { "type": "string" } } }, "DraftInput": { "type": "object", "required": [ "service_date", "shipments" ], "properties": { "external_reference": { "type": "string", "maxLength": 100, "description": "Referencia del pedido en tu sistema; evita duplicados al reintentar" }, "shipper_id": { "type": "integer" }, "shipper_nif": { "type": "string" }, "carrier_id": { "type": "integer" }, "carrier_nif": { "type": "string" }, "vehicle_id": { "type": "integer" }, "vehicle_plate": { "type": "string" }, "driver_id": { "type": "integer" }, "driver_nif": { "type": "string" }, "document_date": { "type": "string", "format": "date", "description": "Por defecto, hoy" }, "service_date": { "type": "string", "format": "date", "description": "Hoy o posterior" }, "observations": { "type": "string" }, "shipments": { "type": "array", "minItems": 1, "maxItems": 200, "items": { "$ref": "#/definitions/DraftShipmentInput" } } } }, "Draft": { "type": "object", "properties": { "id": { "type": "integer" }, "reference": { "type": "string" }, "type": { "type": "string" }, "status": { "type": "string", "description": "draft hasta que se emite" }, "external_reference": { "type": "string", "x-nullable": true }, "edit_url": { "type": "string", "format": "uri" }, "shipper_id": { "type": "integer", "x-nullable": true }, "carrier_id": { "type": "integer", "x-nullable": true }, "vehicle_id": { "type": "integer", "x-nullable": true }, "driver_id": { "type": "integer", "x-nullable": true }, "document_date": { "type": "string", "format": "date" }, "service_date": { "type": "string", "format": "date" }, "observations": { "type": "string", "x-nullable": true }, "shipments": { "type": "array", "items": { "type": "object" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "revision": { "type": "integer", "minimum": 0 }, "document_data": { "$ref": "#/definitions/NativeDocumentData" } } }, "Counterparty": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "country": { "type": "string" }, "nif": { "type": "string" }, "address": { "type": "string" }, "roles": { "type": "string" }, "email": { "type": "string", "x-nullable": true }, "updated_at": { "type": "string", "format": "date-time" } } }, "CounterpartyInput": { "type": "object", "required": [ "name", "nif", "address", "roles" ], "properties": { "name": { "type": "string" }, "country": { "type": "string", "default": "ES" }, "nif": { "type": "string" }, "address": { "type": "string" }, "roles": { "type": "string", "description": "Función: cargador, transportista, destinatario o combinaciones, como en la agenda" }, "email": { "type": "string" } } }, "Vehicle": { "type": "object", "properties": { "id": { "type": "integer" }, "plate": { "type": "string" }, "trailer": { "type": "string", "x-nullable": true }, "description": { "type": "string", "x-nullable": true }, "updated_at": { "type": "string", "format": "date-time" } } }, "VehicleInput": { "type": "object", "required": [ "plate" ], "properties": { "plate": { "type": "string" }, "trailer": { "type": "string" }, "description": { "type": "string" } } }, "Driver": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "country": { "type": "string" }, "nif": { "type": "string" }, "phone": { "type": "string", "x-nullable": true }, "email": { "type": "string", "x-nullable": true }, "updated_at": { "type": "string", "format": "date-time" } } }, "DriverInput": { "type": "object", "required": [ "name", "nif" ], "properties": { "name": { "type": "string" }, "country": { "type": "string", "default": "ES" }, "nif": { "type": "string" }, "phone": { "type": "string" }, "email": { "type": "string" } } }, "WebhookEvent": { "type": "object", "description": "Cuerpo de cada webhook. Cabeceras: DeCAred-Event, DeCAred-Delivery (id del evento) y DeCAred-Signature «t=,v1=», HMAC-SHA256 de \".\" con el secreto del destino. Entrega al menos una vez: deduplica por id. Responde 2xx en menos de 10 segundos.", "properties": { "id": { "type": "string", "format": "uuid" }, "event": { "type": "string", "enum": [ "document.issued", "document.corrected", "document.closed", "document.annulled", "document.receipt_confirmed", "document.service_finished", "ping" ] }, "created_at": { "type": "string", "format": "date-time" }, "company_id": { "type": "integer" }, "data": { "$ref": "#/definitions/Document" } } }, "WebhookSubscription": { "type": "object", "properties": { "id": { "type": "integer" }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string" } }, "created_at": { "type": "string", "format": "date-time" } } }, "CursorPage": { "type": "object", "required": [ "per_page", "has_more", "next_cursor", "sync_until" ], "properties": { "per_page": { "type": "integer" }, "has_more": { "type": "boolean" }, "next_cursor": { "type": "string", "x-nullable": true }, "sync_until": { "type": "string", "format": "date-time", "description": "Limite superior exclusivo del ciclo. Guardar solo tras agotar todas las paginas. Los cambios desde este instante se recuperan en el siguiente ciclo." } } }, "Error": { "type": "object", "required": [ "message", "code", "request_id" ], "properties": { "message": { "type": "string" }, "code": { "type": "string", "example": "validation_failed" }, "request_id": { "type": "string", "format": "uuid" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } } }, "NativeShipment": { "type": "object", "properties": { "origin": { "type": "string", "maxLength": 400 }, "origin_name": { "type": "string" }, "destination": { "type": "string", "maxLength": 400 }, "destination_name": { "type": "string" }, "goods": { "type": "string" }, "weight": { "type": "number", "description": "Peso bruto en kg" }, "alternative": { "type": "string" }, "packages": { "type": "string" }, "packaging": { "type": "string" }, "recipient": { "type": "string" }, "observations": { "type": "string" }, "adr": { "type": "string" }, "expeditor": { "type": "string", "x-nullable": true, "maxLength": 2000 }, "delivery_due": { "type": "string", "x-nullable": true, "maxLength": 2000 }, "contract_payer": { "type": "string", "x-nullable": true, "maxLength": 2000 }, "contract_reference": { "type": "string", "x-nullable": true, "maxLength": 2000 }, "carriage_requested": { "type": "boolean" }, "contract_price": { "type": "number", "x-nullable": true, "minimum": 0, "maximum": 999999999 } }, "additionalProperties": false }, "NativeDocumentData": { "type": "object", "additionalProperties": false, "description": "Campos nativos del editor. PATCH combina solo los campos enviados; shipments sustituye toda la lista. Se permiten borradores incompletos; preparar issue/correct exige la validacion documental completa.", "properties": { "shipper_id": { "type": "integer", "x-nullable": true, "minimum": 1 }, "carrier_id": { "type": "integer", "x-nullable": true, "minimum": 1 }, "contractual_carrier_id": { "type": "integer", "x-nullable": true, "minimum": 1 }, "vehicle_id": { "type": "integer", "x-nullable": true, "minimum": 1 }, "driver_id": { "type": "integer", "x-nullable": true, "minimum": 1 }, "scope": { "type": "string", "x-nullable": true, "maxLength": 2000, "enum": [ "nacional", "cabotaje" ] }, "language": { "type": "string", "x-nullable": true, "maxLength": 2000 }, "date": { "type": "string", "x-nullable": true, "maxLength": 2000 }, "starts_at": { "type": "string", "x-nullable": true, "maxLength": 2000 }, "special_authorization": { "type": "string", "x-nullable": true, "maxLength": 2000 }, "observations": { "type": "string", "x-nullable": true, "maxLength": 2000 }, "contractual_is_company": { "type": "boolean" }, "articulated": { "type": "boolean" }, "special_required": { "type": "boolean" }, "shipments": { "type": "array", "minItems": 1, "maxItems": 200, "items": { "$ref": "#/definitions/NativeShipment" } }, "carriage": { "type": "object", "additionalProperties": false, "properties": { "requested": { "type": "boolean" }, "price": { "type": "number", "x-nullable": true }, "payer": { "type": "string", "enum": [ "shipper", "recipient" ] }, "reference": { "type": "string", "maxLength": 200 } } } } }, "PrepareOperation": { "type": "object", "required": [ "action", "revision" ], "properties": { "action": { "type": "string", "enum": [ "issue", "correct", "close", "annul", "resend", "report_issue", "resolve_issue", "message" ] }, "revision": { "type": "integer", "minimum": 0 }, "data": { "$ref": "#/definitions/NativeDocumentData" }, "reason": { "type": "string", "minLength": 5, "maxLength": 2000 }, "body": { "type": "string", "minLength": 1, "maxLength": 4000 }, "visibility": { "type": "string", "enum": [ "internal", "shared" ], "default": "shared" }, "category": { "type": "string", "enum": [ "access_problem", "data_mismatch", "pickup_delivery", "goods_damaged", "delay", "other" ] }, "priority": { "type": "string", "enum": [ "normal", "high", "urgent" ] }, "urgent_reason": { "type": "string", "minLength": 5, "maxLength": 2000 }, "issue_id": { "type": "integer", "minimum": 1 }, "accept_duplicate": { "type": "boolean", "default": false } } }, "PrepareOperationMultipart": { "type": "object", "required": [ "action", "revision" ], "properties": { "action": { "type": "string", "enum": [ "issue", "correct", "close", "annul", "resend", "report_issue", "resolve_issue", "message" ] }, "revision": { "type": "integer", "minimum": 0 }, "data": { "$ref": "#/definitions/NativeDocumentData" }, "reason": { "type": "string", "minLength": 5, "maxLength": 2000 }, "body": { "type": "string", "minLength": 1, "maxLength": 4000 }, "visibility": { "type": "string", "enum": [ "internal", "shared" ], "default": "shared" }, "category": { "type": "string", "enum": [ "access_problem", "data_mismatch", "pickup_delivery", "goods_damaged", "delay", "other" ] }, "priority": { "type": "string", "enum": [ "normal", "high", "urgent" ] }, "urgent_reason": { "type": "string", "minLength": 5, "maxLength": 2000 }, "issue_id": { "type": "integer", "minimum": 1 }, "accept_duplicate": { "type": "boolean", "default": false }, "attachments": { "type": "array", "maxItems": 3, "items": { "type": "string", "format": "binary" }, "description": "Solo report_issue y message: JPEG, PNG o PDF de hasta 1 MiB, comprobados por contenido. Se almacenan cifrados hasta la confirmacion." } } }, "ApiOperation": { "type": "object", "required": [ "id", "status" ], "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "prepared", "executing", "completed", "uncertain" ] }, "action": { "type": "string", "enum": [ "issue", "correct", "close", "annul", "resend", "report_issue", "resolve_issue", "message" ] }, "expires_at": { "type": "string", "format": "date-time" }, "confirmation_token": { "type": "string", "minLength": 48, "maxLength": 48, "description": "Solo se devuelve al preparar. Se presenta en la confirmacion con la misma clave." }, "summary": { "type": "object", "description": "Resumen exacto que la integracion debe mostrar para la autorizacion; incluye document_data, motivo, texto, prioridad, visibilidad y adjuntos sin contenido." }, "result": { "type": "object", "x-nullable": true, "description": "Identificadores de documento, version, incidencia, mensaje o entrega, segun la accion." }, "replayed": { "type": "boolean", "description": "true si la confirmacion devuelve el resultado ya registrado, sin repetir el efecto." } } }, "TrackingSummary": { "type": "object", "properties": { "document_id": { "type": "integer" }, "revision": { "type": "integer" }, "status": { "type": "string" }, "current_version_id": { "type": "integer" }, "current_version": { "type": "integer" }, "send_state": { "type": "string" }, "receipt_state": { "type": "string" }, "confirmed_at": { "type": "string", "format": "date-time", "x-nullable": true }, "confirmed_version_number": { "type": "integer", "x-nullable": true }, "service_finished_at": { "type": "string", "x-nullable": true }, "open_issues": { "type": "integer" }, "urgent_issues": { "type": "integer" }, "gaps": { "type": "array", "items": { "type": "object" } }, "signature_counts": { "type": "object" } } }, "DeliveryRecord": { "type": "object", "properties": { "id": { "type": "integer" }, "document_version_id": { "type": "integer", "x-nullable": true }, "driver_id": { "type": "integer", "x-nullable": true }, "channel": { "type": "string", "x-nullable": true }, "status": { "type": "string", "x-nullable": true }, "created_at": { "type": "string", "x-nullable": true }, "updated_at": { "type": "string", "x-nullable": true }, "status_label": { "type": "string", "x-nullable": true } } }, "InteractionRecord": { "type": "object", "properties": { "id": { "type": "integer" }, "document_version_id": { "type": "integer", "x-nullable": true }, "driver_id": { "type": "integer", "x-nullable": true }, "type": { "type": "string", "x-nullable": true }, "source": { "type": "string", "x-nullable": true }, "was_current": { "type": "boolean", "x-nullable": true }, "created_at": { "type": "string", "x-nullable": true } } }, "IssueRecord": { "type": "object", "properties": { "id": { "type": "integer" }, "document_version_id": { "type": "integer", "x-nullable": true }, "driver_id": { "type": "integer", "x-nullable": true }, "source": { "type": "string", "x-nullable": true }, "category": { "type": "string", "x-nullable": true }, "priority": { "type": "string", "x-nullable": true }, "urgent_reason": { "type": "string", "x-nullable": true }, "status": { "type": "string", "x-nullable": true }, "assignee_id": { "type": "integer", "x-nullable": true }, "due_at": { "type": "string", "x-nullable": true }, "resolution": { "type": "string", "x-nullable": true }, "resolved_at": { "type": "string", "x-nullable": true }, "created_at": { "type": "string", "x-nullable": true }, "updated_at": { "type": "string", "x-nullable": true } } }, "IssueEventRecord": { "type": "object", "properties": { "id": { "type": "integer" }, "tracking_issue_id": { "type": "integer", "x-nullable": true }, "user_id": { "type": "integer", "x-nullable": true }, "action": { "type": "string", "x-nullable": true }, "details": { "type": "object", "x-nullable": true }, "created_at": { "type": "string", "x-nullable": true } } }, "MessageRecord": { "type": "object", "properties": { "id": { "type": "integer" }, "document_version_id": { "type": "integer", "x-nullable": true }, "tracking_issue_id": { "type": "integer", "x-nullable": true }, "direction": { "type": "string", "x-nullable": true }, "visibility": { "type": "string", "x-nullable": true }, "body": { "type": "string", "x-nullable": true }, "created_at": { "type": "string", "x-nullable": true }, "telegram_state": { "type": "string", "x-nullable": true } } }, "AttachmentRecord": { "type": "object", "properties": { "id": { "type": "integer" }, "tracking_issue_id": { "type": "integer", "x-nullable": true }, "tracking_message_id": { "type": "integer", "x-nullable": true }, "name": { "type": "string" }, "mime": { "type": "string" }, "size": { "type": "integer" }, "sha256": { "type": "string" }, "created_at": { "type": "string", "x-nullable": true }, "download_url": { "type": "string", "x-nullable": true } } } }, "securityDefinitions": { "api_key": { "type": "apiKey", "in": "header", "name": "Authorization" } }, "security": [ { "api_key": [] } ], "x-ms-connector-metadata": [ { "propertyName": "Website", "propertyValue": "https://decared.com" }, { "propertyName": "Privacy policy", "propertyValue": "https://decared.com/legal/privacidad" }, { "propertyName": "Categories", "propertyValue": "Productivity;Data" } ] }