{ "openapi": "3.0.3", "info": { "title": "API de 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" }, "license": { "name": "Uso sujeto a los términos de DeCAred", "url": "https://decared.com/legal/terminos" } }, "servers": [ { "url": "https://decared.com/api/v1" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Cuenta", "description": "Comprobar la conexión." }, { "name": "Documentos", "description": "DeCA, hojas de ruta y cartas de porte emitidos." }, { "name": "Borradores", "description": "Borradores de DeCA creados desde otro sistema." }, { "name": "Agenda", "description": "Empresas de la agenda, vehículos y conductores." }, { "name": "Webhooks", "description": "Suscripciones a avisos automáticos, para plataformas como Zapier, Make o Power Automate." }, { "name": "Seguimiento", "description": "Estado y expediente operativo privado." }, { "name": "Operaciones", "description": "Propuesta y confirmacion de acciones de oficina." } ], "paths": { "/me": { "get": { "tags": [ "Cuenta" ], "operationId": "me", "summary": "Empresa y permisos de la clave", "responses": { "200": { "description": "Empresa de la clave", "content": { "application/json": { "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" ] } } } } } } } } } }, "headers": { "X-Request-ID": { "schema": { "type": "string", "format": "uuid" }, "description": "Identificador de la peticion para soporte." } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/documents": { "get": { "tags": [ "Documentos" ], "operationId": "listDocuments", "summary": "Documentos emitidos, del último cambio al más antiguo", "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", "description": "Referencia exacta, por ejemplo DECA-2026-001095", "schema": { "type": "string" } }, { "name": "external_reference", "in": "query", "description": "Referencia del pedido en tu sistema", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "open", "closed", "annulled" ] } }, { "name": "type", "in": "query", "schema": { "type": "string", "enum": [ "deca", "route_sheet", "carriage_letter" ] } }, { "name": "updated_since", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "$ref": "#/components/parameters/Pagination" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "Página de documentos", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Document" } }, "meta": { "oneOf": [ { "$ref": "#/components/schemas/Page" }, { "$ref": "#/components/schemas/CursorPage" } ] } } } } }, "headers": { "X-Request-ID": { "schema": { "type": "string", "format": "uuid" }, "description": "Identificador de la peticion para soporte." } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "422": { "$ref": "#/components/responses/Invalid" } }, "x-required-ability": "documents:read" } }, "/documents/{id}": { "get": { "tags": [ "Documentos" ], "operationId": "getDocument", "summary": "Detalle de un documento con todas sus versiones", "parameters": [ { "$ref": "#/components/parameters/Id" } ], "responses": { "200": { "description": "Documento", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Document" } } } } }, "headers": { "X-Request-ID": { "schema": { "type": "string", "format": "uuid" }, "description": "Identificador de la peticion para soporte." } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-required-ability": "documents:read", "description": " Permiso especifico: documents:read. Las claves generales read/write conservan sus permisos anteriores." } }, "/documents/{id}/versions/{number}/pdf": { "get": { "tags": [ "Documentos" ], "operationId": "downloadPdf", "summary": "PDF de una versión", "description": "Se comprueba su huella SHA-256 antes de servirlo; la cabecera X-Content-SHA256 la repite. Permiso especifico: documents:read. Las claves generales read/write conservan sus permisos anteriores.", "parameters": [ { "$ref": "#/components/parameters/Id" }, { "name": "number", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "PDF", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string", "format": "uuid" }, "description": "Identificador de la peticion para soporte." } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-required-ability": "documents:read" } }, "/drafts": { "post": { "tags": [ "Borradores" ], "operationId": "createDraft", "summary": "Crear un 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.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DraftInput" } } } }, "responses": { "201": { "description": "Borrador creado", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Draft" } } } } }, "headers": { "X-Request-ID": { "schema": { "type": "string", "format": "uuid" }, "description": "Identificador de la peticion para soporte." } } }, "200": { "description": "Ya existía un borrador con ese external_reference", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Draft" } } } } }, "headers": { "Idempotent-Replayed": { "schema": { "type": "string", "enum": [ "true" ] }, "description": "Se devuelve el registro existente sin repetir la creacion." }, "X-Request-ID": { "schema": { "type": "string", "format": "uuid" }, "description": "Identificador de la peticion para soporte." } } }, "422": { "$ref": "#/components/responses/Invalid" }, "409": { "$ref": "#/components/responses/Conflict" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-required-ability": "drafts:write" }, "get": { "tags": [ "Borradores" ], "operationId": "listDrafts", "summary": "Consultar borradores de DeCA 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", "schema": { "type": "string", "maxLength": 100 } }, { "$ref": "#/components/parameters/UpdatedSince" }, { "$ref": "#/components/parameters/PerPage" }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 } }, { "$ref": "#/components/parameters/Pagination" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "Borradores pendientes", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Draft" } }, "meta": { "oneOf": [ { "$ref": "#/components/schemas/Page" }, { "$ref": "#/components/schemas/CursorPage" } ] } } } } }, "headers": { "X-Request-ID": { "schema": { "type": "string", "format": "uuid" }, "description": "Identificador de la peticion para soporte." } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "422": { "$ref": "#/components/responses/Invalid" } }, "x-required-ability": "drafts:read" } }, "/drafts/{id}": { "get": { "tags": [ "Borradores" ], "operationId": "getDraft", "summary": "Estado de un borrador creado por la API", "parameters": [ { "$ref": "#/components/parameters/Id" } ], "responses": { "200": { "description": "Borrador", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Draft" } } } } }, "headers": { "X-Request-ID": { "schema": { "type": "string", "format": "uuid" }, "description": "Identificador de la peticion para soporte." } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-required-ability": "drafts:read", "description": " Permiso especifico: drafts:read. Las claves generales read/write conservan sus permisos anteriores." }, "patch": { "tags": [ "Operaciones" ], "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": [ { "$ref": "#/components/parameters/Id" } ], "responses": { "200": { "description": "Modificar un borrador sin emitir", "headers": { "X-Request-ID": { "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Draft" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/OperationConflict" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-required-ability": "drafts:edit", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "revision", "data" ], "properties": { "revision": { "type": "integer", "minimum": 0 }, "data": { "$ref": "#/components/schemas/NativeDocumentData" } } } } } } } }, "/counterparties": { "get": { "tags": [ "Agenda" ], "operationId": "listCounterparties", "summary": "Empresas de la agenda", "parameters": [ { "$ref": "#/components/parameters/UpdatedSince" }, { "$ref": "#/components/parameters/PerPage" }, { "$ref": "#/components/parameters/Pagination" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "Página", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Counterparty" } }, "meta": { "oneOf": [ { "$ref": "#/components/schemas/Page" }, { "$ref": "#/components/schemas/CursorPage" } ] } } } } }, "headers": { "X-Request-ID": { "schema": { "type": "string", "format": "uuid" }, "description": "Identificador de la peticion para soporte." } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "422": { "$ref": "#/components/responses/Invalid" } }, "x-required-ability": "counterparties:read", "description": " Permiso especifico: counterparties:read. Las claves generales read/write conservan sus permisos anteriores." }, "post": { "tags": [ "Agenda" ], "operationId": "upsertCounterparty", "summary": "Crear o actualizar por NIF", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CounterpartyInput" } } } }, "responses": { "201": { "description": "Creada", "headers": { "X-Request-ID": { "schema": { "type": "string", "format": "uuid" }, "description": "Identificador de la peticion para soporte." } } }, "200": { "description": "Actualizada", "headers": { "X-Request-ID": { "schema": { "type": "string", "format": "uuid" }, "description": "Identificador de la peticion para soporte." } } }, "422": { "$ref": "#/components/responses/Invalid" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-required-ability": "counterparties:write", "description": " Permiso especifico: counterparties:write. Las claves generales read/write conservan sus permisos anteriores." } }, "/vehicles": { "get": { "tags": [ "Agenda" ], "operationId": "listVehicles", "summary": "Vehículos", "parameters": [ { "$ref": "#/components/parameters/UpdatedSince" }, { "$ref": "#/components/parameters/PerPage" }, { "$ref": "#/components/parameters/Pagination" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "Página", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Vehicle" } }, "meta": { "oneOf": [ { "$ref": "#/components/schemas/Page" }, { "$ref": "#/components/schemas/CursorPage" } ] } } } } }, "headers": { "X-Request-ID": { "schema": { "type": "string", "format": "uuid" }, "description": "Identificador de la peticion para soporte." } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "422": { "$ref": "#/components/responses/Invalid" } }, "x-required-ability": "vehicles:read", "description": " Permiso especifico: vehicles:read. Las claves generales read/write conservan sus permisos anteriores." }, "post": { "tags": [ "Agenda" ], "operationId": "upsertVehicle", "summary": "Crear o actualizar por matrícula", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VehicleInput" } } } }, "responses": { "201": { "description": "Creado", "headers": { "X-Request-ID": { "schema": { "type": "string", "format": "uuid" }, "description": "Identificador de la peticion para soporte." } } }, "200": { "description": "Actualizado", "headers": { "X-Request-ID": { "schema": { "type": "string", "format": "uuid" }, "description": "Identificador de la peticion para soporte." } } }, "422": { "$ref": "#/components/responses/Invalid" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-required-ability": "vehicles:write", "description": " Permiso especifico: vehicles:write. Las claves generales read/write conservan sus permisos anteriores." } }, "/drivers": { "get": { "tags": [ "Agenda" ], "operationId": "listDrivers", "summary": "Conductores", "parameters": [ { "$ref": "#/components/parameters/UpdatedSince" }, { "$ref": "#/components/parameters/PerPage" }, { "$ref": "#/components/parameters/Pagination" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "Página", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Driver" } }, "meta": { "oneOf": [ { "$ref": "#/components/schemas/Page" }, { "$ref": "#/components/schemas/CursorPage" } ] } } } } }, "headers": { "X-Request-ID": { "schema": { "type": "string", "format": "uuid" }, "description": "Identificador de la peticion para soporte." } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "422": { "$ref": "#/components/responses/Invalid" } }, "x-required-ability": "drivers:read", "description": " Permiso especifico: drivers:read. Las claves generales read/write conservan sus permisos anteriores." }, "post": { "tags": [ "Agenda" ], "operationId": "upsertDriver", "summary": "Crear o actualizar por NIF", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DriverInput" } } } }, "responses": { "201": { "description": "Creado", "headers": { "X-Request-ID": { "schema": { "type": "string", "format": "uuid" }, "description": "Identificador de la peticion para soporte." } } }, "200": { "description": "Actualizado", "headers": { "X-Request-ID": { "schema": { "type": "string", "format": "uuid" }, "description": "Identificador de la peticion para soporte." } } }, "422": { "$ref": "#/components/responses/Invalid" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-required-ability": "drivers:write", "description": " Permiso especifico: drivers:write. Las claves generales read/write conservan sus permisos anteriores." } }, "/webhooks": { "get": { "tags": [ "Webhooks" ], "operationId": "listWebhooks", "summary": "Destinos de webhooks activos de la empresa", "responses": { "200": { "description": "Destinos", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookSubscription" } } } } } }, "headers": { "X-Request-ID": { "schema": { "type": "string", "format": "uuid" }, "description": "Identificador de la peticion para soporte." } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-required-ability": "webhooks:manage", "description": " Permiso especifico: webhooks:manage. Las claves generales read/write conservan sus permisos anteriores." }, "post": { "tags": [ "Webhooks" ], "operationId": "subscribeWebhook", "summary": "Suscribir una dirección https a uno o varios eventos", "description": "Devuelve el secreto de firma una sola vez. Actúa en nombre del usuario que creó la clave, que debe seguir pudiendo gestionar las integraciones de la empresa. Permiso especifico: webhooks:manage. Las claves generales read/write conservan sus permisos anteriores.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url", "events" ], "properties": { "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "document.issued", "document.corrected", "document.closed", "document.annulled", "document.receipt_confirmed", "document.service_finished" ] } } } } } } }, "responses": { "201": { "description": "Suscrito", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/WebhookSubscription" }, { "type": "object", "properties": { "secret": { "type": "string" } } } ] } } } } }, "headers": { "X-Request-ID": { "schema": { "type": "string", "format": "uuid" }, "description": "Identificador de la peticion para soporte." } } }, "422": { "$ref": "#/components/responses/Invalid" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-required-ability": "webhooks:manage" } }, "/webhooks/{id}": { "delete": { "tags": [ "Webhooks" ], "operationId": "unsubscribeWebhook", "summary": "Dar de baja una suscripción", "parameters": [ { "$ref": "#/components/parameters/Id" } ], "responses": { "204": { "description": "Eliminada", "headers": { "X-Request-ID": { "schema": { "type": "string", "format": "uuid" }, "description": "Identificador de la peticion para soporte." } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-required-ability": "webhooks:manage", "description": " Permiso especifico: webhooks:manage. Las claves generales read/write conservan sus permisos anteriores." } }, "/documents/{id}/actions": { "post": { "tags": [ "Operaciones" ], "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": [ { "$ref": "#/components/parameters/Id" } ], "responses": { "201": { "description": "Preparar una operacion de oficina", "headers": { "X-Request-ID": { "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ApiOperation" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/OperationConflict" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrepareOperation" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/PrepareOperationMultipart" } } } } } }, "/operations/{operation}": { "get": { "tags": [ "Operaciones" ], "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, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Consultar el resultado de una operacion", "headers": { "X-Request-ID": { "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ApiOperation" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/OperationConflict" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/operations/{operation}/confirm": { "post": { "tags": [ "Operaciones" ], "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.", "parameters": [ { "name": "operation", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Confirmar exactamente la propuesta preparada", "headers": { "X-Request-ID": { "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ApiOperation" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/OperationConflict" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "confirmed", "confirmation_token" ], "properties": { "confirmed": { "type": "boolean", "enum": [ true ] }, "confirmation_token": { "type": "string", "minLength": 48, "maxLength": 48 } } } } } } } }, "/documents/{id}/tracking": { "get": { "tags": [ "Seguimiento" ], "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": [ { "$ref": "#/components/parameters/Id" } ], "responses": { "200": { "description": "Consultar el estado de seguimiento", "headers": { "X-Request-ID": { "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/TrackingSummary" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/OperationConflict" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-required-ability": "tracking:read" } }, "/documents/{id}/tracking/deliveries": { "get": { "tags": [ "Seguimiento" ], "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": [ { "$ref": "#/components/parameters/Id" }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "$ref": "#/components/parameters/PerPage" } ], "responses": { "200": { "description": "Pagina de deliveries", "headers": { "X-Request-ID": { "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DeliveryRecord" } }, "meta": { "$ref": "#/components/schemas/Page" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/OperationConflict" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-required-ability": "tracking:read" } }, "/documents/{id}/tracking/interactions": { "get": { "tags": [ "Seguimiento" ], "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": [ { "$ref": "#/components/parameters/Id" }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "$ref": "#/components/parameters/PerPage" } ], "responses": { "200": { "description": "Pagina de interactions", "headers": { "X-Request-ID": { "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/InteractionRecord" } }, "meta": { "$ref": "#/components/schemas/Page" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/OperationConflict" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-required-ability": "tracking:read" } }, "/documents/{id}/tracking/issues": { "get": { "tags": [ "Seguimiento" ], "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": [ { "$ref": "#/components/parameters/Id" }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "$ref": "#/components/parameters/PerPage" } ], "responses": { "200": { "description": "Pagina de issues", "headers": { "X-Request-ID": { "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/IssueRecord" } }, "meta": { "$ref": "#/components/schemas/Page" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/OperationConflict" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-required-ability": "tracking:read" } }, "/documents/{id}/tracking/issue_events": { "get": { "tags": [ "Seguimiento" ], "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": [ { "$ref": "#/components/parameters/Id" }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "$ref": "#/components/parameters/PerPage" } ], "responses": { "200": { "description": "Pagina de issue_events", "headers": { "X-Request-ID": { "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/IssueEventRecord" } }, "meta": { "$ref": "#/components/schemas/Page" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/OperationConflict" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-required-ability": "tracking:read" } }, "/documents/{id}/tracking/messages": { "get": { "tags": [ "Seguimiento" ], "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": [ { "$ref": "#/components/parameters/Id" }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "$ref": "#/components/parameters/PerPage" } ], "responses": { "200": { "description": "Pagina de messages", "headers": { "X-Request-ID": { "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MessageRecord" } }, "meta": { "$ref": "#/components/schemas/Page" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/OperationConflict" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-required-ability": "tracking:read" } }, "/documents/{id}/tracking/attachments": { "get": { "tags": [ "Seguimiento" ], "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": [ { "$ref": "#/components/parameters/Id" }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "$ref": "#/components/parameters/PerPage" } ], "responses": { "200": { "description": "Pagina de attachments", "headers": { "X-Request-ID": { "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AttachmentRecord" } }, "meta": { "$ref": "#/components/schemas/Page" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/OperationConflict" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-required-ability": "tracking:read" } }, "/documents/{id}/attachments/{attachment}": { "get": { "tags": [ "Operaciones" ], "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": [ { "$ref": "#/components/parameters/Id" }, { "name": "attachment", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "JPEG, PNG o PDF original", "content": { "image/jpeg": { "schema": { "type": "string", "format": "binary" } }, "image/png": { "schema": { "type": "string", "format": "binary" } }, "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/OperationConflict" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-required-ability": "attachments:read" } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Clave de API de la empresa (dcr_…), creada en DeCAred → Integraciones." } }, "parameters": { "Id": { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, "UpdatedSince": { "name": "updated_since", "in": "query", "schema": { "type": "string", "format": "date-time" }, "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." }, "PerPage": { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, "Pagination": { "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.", "schema": { "type": "string", "enum": [ "page", "cursor" ], "default": "page" } }, "Cursor": { "name": "cursor", "in": "query", "description": "Token opaco next_cursor. Conservar los filtros originales. Ligado a empresa, recurso y filtros; caduca a las 24 horas.", "schema": { "type": "string", "maxLength": 8192 } } }, "responses": { "Unauthorized": { "description": "Clave ausente, no válida o revocada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string", "format": "uuid" } } } }, "Forbidden": { "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", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string", "format": "uuid" } } } }, "NotFound": { "description": "No existe en esta empresa", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string", "format": "uuid" } } } }, "Invalid": { "description": "Datos no válidos", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string", "format": "uuid" } } } }, "TooManyRequests": { "description": "Más de 120 peticiones por minuto con esta clave; espera los segundos de Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Segundos antes de reintentar." }, "X-Request-ID": { "schema": { "type": "string", "format": "uuid" } } } }, "Conflict": { "description": "external_reference ya utilizada con un contenido diferente (external_reference_conflict). Los borradores anteriores a 1.2 sin huella conservan el comportamiento anterior.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string", "format": "uuid" } } } }, "OperationConflict": { "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "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", "nullable": true } } }, "Party": { "type": "object", "nullable": true, "properties": { "name": { "type": "string" }, "nif": { "type": "string" }, "address": { "type": "string" } } }, "Shipment": { "type": "object", "properties": { "shipment_reference": { "type": "string" }, "carriage_reference": { "type": "string", "nullable": true }, "origin": { "type": "string" }, "origin_name": { "type": "string", "nullable": true }, "destination": { "type": "string" }, "destination_name": { "type": "string", "nullable": true }, "goods": { "type": "string" }, "weight": { "type": "string", "nullable": true, "description": "Peso bruto en kg" }, "alternative": { "type": "string", "nullable": true, "description": "Otra medida si no hay peso" }, "packages": { "type": "string", "nullable": true }, "packaging": { "type": "string", "nullable": true }, "adr": { "type": "string", "nullable": true }, "recipient": { "type": "string", "nullable": true }, "observations": { "type": "string", "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", "nullable": true }, "accompanies_carriage_letter_id": { "type": "integer", "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", "nullable": true }, "annulled_at": { "type": "string", "format": "date-time", "nullable": true }, "annulment_reason": { "type": "string", "nullable": true }, "updated_at": { "type": "string", "format": "date-time" }, "current_version": { "$ref": "#/components/schemas/Version" }, "versions": { "type": "array", "items": { "$ref": "#/components/schemas/Version" }, "description": "Solo en el detalle" }, "company": { "$ref": "#/components/schemas/Party" }, "shipper": { "$ref": "#/components/schemas/Party" }, "carrier": { "$ref": "#/components/schemas/Party" }, "vehicle": { "type": "object", "nullable": true, "properties": { "plate": { "type": "string" }, "trailer": { "type": "string", "nullable": true } } }, "driver": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "shipments": { "type": "array", "items": { "$ref": "#/components/schemas/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": "#/components/schemas/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", "nullable": true }, "edit_url": { "type": "string", "format": "uri" }, "shipper_id": { "type": "integer", "nullable": true }, "carrier_id": { "type": "integer", "nullable": true }, "vehicle_id": { "type": "integer", "nullable": true }, "driver_id": { "type": "integer", "nullable": true }, "document_date": { "type": "string", "format": "date" }, "service_date": { "type": "string", "format": "date" }, "observations": { "type": "string", "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": "#/components/schemas/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", "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", "nullable": true }, "description": { "type": "string", "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", "nullable": true }, "email": { "type": "string", "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": "#/components/schemas/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", "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", "nullable": true, "maxLength": 2000 }, "delivery_due": { "type": "string", "nullable": true, "maxLength": 2000 }, "contract_payer": { "type": "string", "nullable": true, "maxLength": 2000 }, "contract_reference": { "type": "string", "nullable": true, "maxLength": 2000 }, "carriage_requested": { "type": "boolean" }, "contract_price": { "type": "number", "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", "nullable": true, "minimum": 1 }, "carrier_id": { "type": "integer", "nullable": true, "minimum": 1 }, "contractual_carrier_id": { "type": "integer", "nullable": true, "minimum": 1 }, "vehicle_id": { "type": "integer", "nullable": true, "minimum": 1 }, "driver_id": { "type": "integer", "nullable": true, "minimum": 1 }, "scope": { "type": "string", "nullable": true, "maxLength": 2000, "enum": [ "nacional", "cabotaje" ] }, "language": { "type": "string", "nullable": true, "maxLength": 2000 }, "date": { "type": "string", "nullable": true, "maxLength": 2000 }, "starts_at": { "type": "string", "nullable": true, "maxLength": 2000 }, "special_authorization": { "type": "string", "nullable": true, "maxLength": 2000 }, "observations": { "type": "string", "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": "#/components/schemas/NativeShipment" } }, "carriage": { "type": "object", "additionalProperties": false, "properties": { "requested": { "type": "boolean" }, "price": { "type": "number", "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": "#/components/schemas/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": "#/components/schemas/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", "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", "nullable": true }, "confirmed_version_number": { "type": "integer", "nullable": true }, "service_finished_at": { "type": "string", "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", "nullable": true }, "driver_id": { "type": "integer", "nullable": true }, "channel": { "type": "string", "nullable": true }, "status": { "type": "string", "nullable": true }, "created_at": { "type": "string", "nullable": true }, "updated_at": { "type": "string", "nullable": true }, "status_label": { "type": "string", "nullable": true } } }, "InteractionRecord": { "type": "object", "properties": { "id": { "type": "integer" }, "document_version_id": { "type": "integer", "nullable": true }, "driver_id": { "type": "integer", "nullable": true }, "type": { "type": "string", "nullable": true }, "source": { "type": "string", "nullable": true }, "was_current": { "type": "boolean", "nullable": true }, "created_at": { "type": "string", "nullable": true } } }, "IssueRecord": { "type": "object", "properties": { "id": { "type": "integer" }, "document_version_id": { "type": "integer", "nullable": true }, "driver_id": { "type": "integer", "nullable": true }, "source": { "type": "string", "nullable": true }, "category": { "type": "string", "nullable": true }, "priority": { "type": "string", "nullable": true }, "urgent_reason": { "type": "string", "nullable": true }, "status": { "type": "string", "nullable": true }, "assignee_id": { "type": "integer", "nullable": true }, "due_at": { "type": "string", "nullable": true }, "resolution": { "type": "string", "nullable": true }, "resolved_at": { "type": "string", "nullable": true }, "created_at": { "type": "string", "nullable": true }, "updated_at": { "type": "string", "nullable": true } } }, "IssueEventRecord": { "type": "object", "properties": { "id": { "type": "integer" }, "tracking_issue_id": { "type": "integer", "nullable": true }, "user_id": { "type": "integer", "nullable": true }, "action": { "type": "string", "nullable": true }, "details": { "type": "object", "nullable": true }, "created_at": { "type": "string", "nullable": true } } }, "MessageRecord": { "type": "object", "properties": { "id": { "type": "integer" }, "document_version_id": { "type": "integer", "nullable": true }, "tracking_issue_id": { "type": "integer", "nullable": true }, "direction": { "type": "string", "nullable": true }, "visibility": { "type": "string", "nullable": true }, "body": { "type": "string", "nullable": true }, "created_at": { "type": "string", "nullable": true }, "telegram_state": { "type": "string", "nullable": true } } }, "AttachmentRecord": { "type": "object", "properties": { "id": { "type": "integer" }, "tracking_issue_id": { "type": "integer", "nullable": true }, "tracking_message_id": { "type": "integer", "nullable": true }, "name": { "type": "string" }, "mime": { "type": "string" }, "size": { "type": "integer" }, "sha256": { "type": "string" }, "created_at": { "type": "string", "nullable": true }, "download_url": { "type": "string", "nullable": true } } } } } }