{ "openapi": "3.0.3", "info": { "title": "All True Detection API", "version": "1.1.0", "description": "API privada por cuenta para solicitudes, documentos escritos, entregas y facturación comercial. Importes enteros en unidades menores. HTTPS en producción; Bearer con scopes; sin confirmación de pagos por API." }, "servers": [ { "url": "/api/v1" } ], "security": [ { "BearerAuth": [] } ], "paths": { "/services": { "get": { "operationId": "listServices", "description": "Requiere orders:read", "responses": { "200": { "description": "Respuesta", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Service" } } } } } }, "headers": { "X-Request-ID": { "schema": { "type": "string", "format": "uuid" } } } }, "401": { "description": "Error de autenticación, autorización, conflicto, validación o servidor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error de autenticación, autorización, conflicto, validación o servidor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error de autenticación, autorización, conflicto, validación o servidor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error de autenticación, autorización, conflicto, validación o servidor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error de autenticación, autorización, conflicto, validación o servidor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "426": { "description": "HTTPS requerido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error de autenticación, autorización, conflicto, validación o servidor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error de autenticación, autorización, conflicto, validación o servidor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio temporalmente no disponible (incluido escáner de documentos)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "orders:read" ] } }, "/orders": { "get": { "operationId": "listOrders", "description": "Requiere orders:read", "parameters": [ { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "status", "in": "query", "schema": { "$ref": "#/components/schemas/OrderStatus" } }, { "name": "external_reference", "in": "query", "schema": { "type": "string", "maxLength": 100 } } ], "responses": { "200": { "description": "Respuesta", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Order" } }, "links": { "type": "object" }, "meta": { "type": "object" } } } } }, "headers": { "X-Request-ID": { "schema": { "type": "string", "format": "uuid" } } } }, "401": { "description": "Error de autenticación, autorización, conflicto, validación o servidor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error de autenticación, autorización, conflicto, validación o servidor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error de autenticación, autorización, conflicto, validación o servidor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error de autenticación, autorización, conflicto, validación o servidor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error de autenticación, autorización, conflicto, validación o servidor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "426": { "description": "HTTPS requerido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error de autenticación, autorización, conflicto, validación o servidor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error de autenticación, autorización, conflicto, validación o servidor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio temporalmente no disponible (incluido escáner de documentos)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "orders:read" ] }, "post": { "operationId": "createOrder", "description": "Requiere orders:write. Misma clave y payload reproduce la orden; cambios producen 409.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{8,128}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrder" } } } }, "responses": { "201": { "description": "Respuesta", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Order" }, "meta": { "type": "object" } } } } } }, "400": { "description": "Formato de contenido o JSON no válido / límite de tamaño", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error de autenticación, autorización, conflicto, validación o servidor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error de autenticación, autorización, conflicto, validación o servidor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error de autenticación, autorización, conflicto, validación o servidor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error de autenticación, autorización, conflicto, validación o servidor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Formato de contenido o JSON no válido / límite de tamaño", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Formato de contenido o JSON no válido / límite de tamaño", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error de autenticación, autorización, conflicto, validación o servidor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "426": { "description": "HTTPS requerido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error de autenticación, autorización, conflicto, validación o servidor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error de autenticación, autorización, conflicto, validación o servidor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio temporalmente no disponible (incluido escáner de documentos)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "orders:write" ] } }, "/orders/{order}": { "parameters": [ { "name": "order", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" } } ], "get": { "operationId": "getOrder", "description": "Requiere orders:read", "responses": { "200": { "description": "Respuesta", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Order" }, "meta": { "type": "object" } } } } }, "headers": { "X-Request-ID": { "schema": { "type": "string", "format": "uuid" } } } }, "401": { "description": "Error de autenticación, autorización, conflicto, validación o servidor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error de autenticación, autorización, conflicto, validación o servidor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error de autenticación, autorización, conflicto, validación o servidor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error de autenticación, autorización, conflicto, validación o servidor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error de autenticación, autorización, conflicto, validación o servidor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "426": { "description": "HTTPS requerido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error de autenticación, autorización, conflicto, validación o servidor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error de autenticación, autorización, conflicto, validación o servidor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio temporalmente no disponible (incluido escáner de documentos)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "orders:read" ] } }, "/orders/{order}/results": { "parameters": [ { "name": "order", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" } } ], "get": { "operationId": "listResults", "description": "Requiere results:read. Solo orden completada, factura pagada y entregas publicadas.", "responses": { "200": { "description": "Respuesta", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Result" } }, "links": { "type": "object" }, "meta": { "type": "object" } } } } }, "headers": { "X-Request-ID": { "schema": { "type": "string", "format": "uuid" } } } }, "401": { "description": "Error de autenticación, autorización, conflicto, validación o servidor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error de autenticación, autorización, conflicto, validación o servidor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error de autenticación, autorización, conflicto, validación o servidor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error de autenticación, autorización, conflicto, validación o servidor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error de autenticación, autorización, conflicto, validación o servidor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "426": { "description": "HTTPS requerido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error de autenticación, autorización, conflicto, validación o servidor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error de autenticación, autorización, conflicto, validación o servidor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio temporalmente no disponible (incluido escáner de documentos)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "results:read" ] } }, "/orders/{order}/results/{result}/download": { "parameters": [ { "name": "order", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" } }, { "name": "result", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "downloadResult", "description": "Requiere results:read; comprueba autorización y pago en cada descarga.", "responses": { "200": { "description": "Archivo privado", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string", "format": "uuid" } }, "X-Content-SHA256": { "schema": { "type": "string" }, "description": "Huella esperada del archivo privado." } } }, "401": { "description": "Error de autenticación, autorización, conflicto, validación o servidor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error de autenticación, autorización, conflicto, validación o servidor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error de autenticación, autorización, conflicto, validación o servidor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error de autenticación, autorización, conflicto, validación o servidor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error de autenticación, autorización, conflicto, validación o servidor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "426": { "description": "HTTPS requerido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error de autenticación, autorización, conflicto, validación o servidor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error de autenticación, autorización, conflicto, validación o servidor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio temporalmente no disponible (incluido escáner de documentos)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "results:read" ] } }, "/orders/{order}/messages": { "parameters": [ { "name": "order", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" } } ], "get": { "operationId": "listMessages", "description": "Requiere messages:read", "responses": { "200": { "description": "Respuesta", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } }, "links": { "type": "object" }, "meta": { "type": "object" } } } } }, "headers": { "X-Request-ID": { "schema": { "type": "string", "format": "uuid" } } } }, "401": { "description": "Error de autenticación, autorización, conflicto, validación o servidor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error de autenticación, autorización, conflicto, validación o servidor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error de autenticación, autorización, conflicto, validación o servidor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error de autenticación, autorización, conflicto, validación o servidor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error de autenticación, autorización, conflicto, validación o servidor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "426": { "description": "HTTPS requerido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error de autenticación, autorización, conflicto, validación o servidor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error de autenticación, autorización, conflicto, validación o servidor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio temporalmente no disponible (incluido escáner de documentos)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "messages:read" ] }, "post": { "operationId": "sendMessage", "description": "Requiere messages:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "body" ], "properties": { "body": { "type": "string", "minLength": 1, "maxLength": 10000 } } } } } }, "responses": { "201": { "description": "Respuesta", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Message" } } } } } }, "400": { "description": "Formato de contenido o JSON no válido / límite de tamaño", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error de autenticación, autorización, conflicto, validación o servidor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error de autenticación, autorización, conflicto, validación o servidor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error de autenticación, autorización, conflicto, validación o servidor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error de autenticación, autorización, conflicto, validación o servidor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Formato de contenido o JSON no válido / límite de tamaño", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Formato de contenido o JSON no válido / límite de tamaño", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error de autenticación, autorización, conflicto, validación o servidor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "426": { "description": "HTTPS requerido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error de autenticación, autorización, conflicto, validación o servidor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error de autenticación, autorización, conflicto, validación o servidor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio temporalmente no disponible (incluido escáner de documentos)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "messages:write" ] } }, "/orders/{order}/attachments": { "parameters": [ { "name": "order", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "listAttachments", "description": "Requiere orders:read. Documentos de entrada de la cuenta.", "responses": { "200": { "description": "Documentos privados", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Attachment" } }, "links": { "type": "object" }, "meta": { "type": "object" } } } } }, "headers": { "X-Request-ID": { "schema": { "type": "string", "format": "uuid" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "426": { "description": "HTTPS requerido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio temporalmente no disponible (incluido escáner de documentos)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "orders:read" ] }, "post": { "operationId": "uploadAttachment", "description": "Requiere orders:write. PDF/DOCX sin macros/JPG/PNG/WebP hasta 10 MB. 30 documentos y 100 MB por solicitud, 1 GB por cuenta. Solo órdenes abiertas; análisis antivirus obligatorio en producción. Audio, video, SVG y Word antiguo se rechazan.", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary" } } } } } }, "responses": { "201": { "description": "Documento privado agregado", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Attachment" } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "426": { "description": "HTTPS requerido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio temporalmente no disponible (incluido escáner de documentos)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": false, "description": "Recomendado para reintentos: misma clave y contenido devuelve el mismo documento; otro contenido produce 409.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{8,128}$" } } ], "x-required-scopes": [ "orders:write" ] } }, "/orders/{order}/attachments/{attachment}/download": { "parameters": [ { "name": "order", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "attachment", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "downloadAttachment", "description": "Requiere orders:read. Revalida autorización de cuenta.", "responses": { "200": { "description": "Documento privado", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string", "format": "uuid" } }, "X-Content-SHA256": { "schema": { "type": "string" }, "description": "Huella esperada del archivo privado." } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "426": { "description": "HTTPS requerido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio temporalmente no disponible (incluido escáner de documentos)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "orders:read" ] } }, "/invoices": { "get": { "operationId": "listInvoices", "tags": [ "Facturación" ], "description": "Requiere invoices:read. Facturas de la cuenta del token, con saldos en unidades menores.", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "unpaid", "paid", "overdue" ] } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "order_id", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Respuesta", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Invoice" } }, "links": { "type": "object" }, "meta": { "type": "object" } } } } }, "headers": { "X-Request-ID": { "schema": { "type": "string", "format": "uuid" } } } }, "400": { "description": "Consulte error.code, error.message y meta.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Consulte error.code, error.message y meta.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Consulte error.code, error.message y meta.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Consulte error.code, error.message y meta.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Consulte error.code, error.message y meta.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Consulte error.code, error.message y meta.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Consulte error.code, error.message y meta.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Consulte error.code, error.message y meta.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "426": { "description": "HTTPS requerido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Consulte error.code, error.message y meta.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Consulte error.code, error.message y meta.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Consulte error.code, error.message y meta.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "invoices:read" ] } }, "/invoices/{invoice}": { "parameters": [ { "name": "invoice", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" } } ], "get": { "operationId": "getInvoice", "tags": [ "Facturación" ], "description": "Requiere invoices:read. Incluye partidas, snapshots de facturación, pagos y saldo. No permite confirmar pagos.", "responses": { "200": { "description": "Respuesta", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Invoice" } } } } }, "headers": { "X-Request-ID": { "schema": { "type": "string", "format": "uuid" } } } }, "400": { "description": "Consulte error.code, error.message y meta.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Consulte error.code, error.message y meta.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Consulte error.code, error.message y meta.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Consulte error.code, error.message y meta.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Consulte error.code, error.message y meta.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Consulte error.code, error.message y meta.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Consulte error.code, error.message y meta.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Consulte error.code, error.message y meta.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "426": { "description": "HTTPS requerido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Consulte error.code, error.message y meta.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Consulte error.code, error.message y meta.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Consulte error.code, error.message y meta.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "invoices:read" ] } }, "/invoices/{invoice}/document": { "parameters": [ { "name": "invoice", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" } } ], "get": { "operationId": "downloadInvoiceDocument", "tags": [ "Facturación" ], "description": "Requiere invoices:read. Documento comercial HTML imprimible, entregado como attachment, sin NCF.", "responses": { "200": { "description": "Factura HTML imprimible", "content": { "text/html": { "schema": { "type": "string" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string", "format": "uuid" } } } }, "400": { "description": "Consulte error.code, error.message y meta.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Consulte error.code, error.message y meta.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Consulte error.code, error.message y meta.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Consulte error.code, error.message y meta.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Consulte error.code, error.message y meta.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Consulte error.code, error.message y meta.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Consulte error.code, error.message y meta.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Consulte error.code, error.message y meta.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "426": { "description": "HTTPS requerido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Consulte error.code, error.message y meta.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Consulte error.code, error.message y meta.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Consulte error.code, error.message y meta.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "invoices:read" ] } }, "/orders/{order}/deliveries": { "parameters": [ { "name": "order", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" } } ], "get": { "operationId": "listPublishedDeliveries", "description": "Manifiesto paginado de entregas publicadas; requiere results:read, orden completada y factura pagada. Descargue cada archivo con Bearer y compare SHA-256.", "responses": { "200": { "description": "Respuesta", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Result" } }, "links": { "type": "object" }, "meta": { "type": "object" } } } } }, "headers": { "X-Request-ID": { "schema": { "type": "string", "format": "uuid" } } } }, "401": { "description": "Error de autenticación, autorización, conflicto, validación o servidor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error de autenticación, autorización, conflicto, validación o servidor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error de autenticación, autorización, conflicto, validación o servidor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error de autenticación, autorización, conflicto, validación o servidor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error de autenticación, autorización, conflicto, validación o servidor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "426": { "description": "HTTPS requerido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error de autenticación, autorización, conflicto, validación o servidor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error de autenticación, autorización, conflicto, validación o servidor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio temporalmente no disponible (incluido escáner de documentos)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "Entregas" ], "x-required-scopes": [ "results:read" ] } }, "/orders/{order}/results/{result}": { "parameters": [ { "name": "order", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" } }, { "name": "result", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" } } ], "get": { "operationId": "getPublishedResult", "tags": [ "Entregas" ], "description": "Requiere results:read y acceso a la cuenta. Solo resultados publicados con pago confirmado.", "responses": { "200": { "description": "Respuesta", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Result" } } } } }, "headers": { "X-Request-ID": { "schema": { "type": "string", "format": "uuid" } } } }, "400": { "description": "Consulte error.code, error.message y meta.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Consulte error.code, error.message y meta.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Consulte error.code, error.message y meta.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Consulte error.code, error.message y meta.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Consulte error.code, error.message y meta.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Consulte error.code, error.message y meta.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Consulte error.code, error.message y meta.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Consulte error.code, error.message y meta.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "426": { "description": "HTTPS requerido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Consulte error.code, error.message y meta.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Consulte error.code, error.message y meta.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Consulte error.code, error.message y meta.request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scopes": [ "results:read" ] } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "description": "Token Sanctum de cliente verificado, activo y con scopes limitados." } }, "schemas": { "OrderStatus": { "type": "string", "enum": [ "submitted", "reviewing", "quoted", "in_progress", "completed", "cancelled" ] }, "Service": { "type": "object", "required": [ "code", "name", "description" ], "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" } } }, "CreateOrder": { "type": "object", "required": [ "subject", "details", "consent", "items" ], "properties": { "subject": { "type": "string", "maxLength": 200 }, "details": { "type": "string", "minLength": 10, "maxLength": 10000 }, "external_reference": { "type": "string", "nullable": true, "maxLength": 100 }, "consent": { "type": "boolean", "enum": [ true ] }, "items": { "type": "array", "minItems": 1, "maxItems": 11, "items": { "type": "object", "additionalProperties": false, "required": [ "service_code", "quantity" ], "properties": { "service_code": { "type": "string" }, "quantity": { "type": "integer", "minimum": 1, "maximum": 100 } } } } } }, "Invoice": { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "string" }, "currency": { "type": "string" }, "subtotal": { "type": "integer" }, "tax_basis_points": { "type": "integer" }, "tax": { "type": "integer" }, "total": { "type": "integer" }, "outstanding": { "type": "integer" }, "status": { "type": "string", "enum": [ "unpaid", "paid" ] }, "issued_at": { "type": "string", "format": "date-time" }, "paid_at": { "type": "string", "nullable": true, "format": "date-time" }, "order_id": { "type": "string" }, "paid_amount": { "type": "integer", "minimum": 0 }, "due_date": { "type": "string", "format": "date", "nullable": true }, "is_overdue": { "type": "boolean" }, "issuer": { "type": "object" }, "recipient": { "type": "object" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "service_name": { "type": "string" }, "quantity": { "type": "integer", "minimum": 0 }, "unit_price": { "type": "integer", "minimum": 0 }, "total": { "type": "integer", "minimum": 0 } } } }, "payments": { "type": "array", "description": "Solo en la ficha individual.", "items": { "type": "object", "properties": { "id": { "type": "string" }, "amount": { "type": "integer", "minimum": 0 }, "method": { "type": "string" }, "reference": { "type": "string" }, "received_at": { "type": "string", "format": "date-time" } } } }, "document_url": { "type": "string", "format": "uri" } } }, "Order": { "type": "object", "properties": { "id": { "type": "string" }, "subject": { "type": "string" }, "details": { "type": "string" }, "external_reference": { "type": "string", "nullable": true }, "status": { "$ref": "#/components/schemas/OrderStatus" }, "items": { "type": "array", "items": { "type": "object", "properties": { "service_code": { "type": "string" }, "service_name": { "type": "string" }, "quantity": { "type": "integer" }, "unit_price": { "type": "integer", "nullable": true } } } }, "invoice": { "allOf": [ { "$ref": "#/components/schemas/Invoice" } ], "nullable": true, "description": "Solo se incluye información de factura si el token tiene invoices:read; en otro caso es null." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "links": { "type": "object" } } }, "Result": { "type": "object", "properties": { "id": { "type": "string" }, "summary": { "type": "string" }, "published_at": { "type": "string", "format": "date-time" }, "file_name": { "type": "string", "nullable": true }, "download_url": { "type": "string", "nullable": true }, "file_size": { "type": "integer", "minimum": 0, "nullable": true }, "sha256": { "type": "string", "nullable": true, "pattern": "^[a-f0-9]{64}$", "description": "SHA-256 del archivo para verificar su integridad." }, "order_id": { "type": "string" }, "mime_type": { "type": "string", "nullable": true } } }, "Message": { "type": "object", "properties": { "id": { "type": "integer" }, "body": { "type": "string" }, "sender": { "type": "string", "enum": [ "ATD", "client" ] }, "created_at": { "type": "string", "format": "date-time" } } }, "Error": { "type": "object", "required": [ "error", "meta" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "fields" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "fields": { "type": "object" } } }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "format": "uuid" } } } } }, "Attachment": { "type": "object", "required": [ "id", "file_name", "mime_type", "created_at", "download_url" ], "properties": { "id": { "type": "string" }, "file_name": { "type": "string" }, "mime_type": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "download_url": { "type": "string" }, "file_size": { "type": "integer", "minimum": 0, "nullable": true }, "sha256": { "type": "string", "nullable": true, "pattern": "^[a-f0-9]{64}$", "description": "SHA-256 del archivo para verificar su integridad." } } }, "WebhookEvent": { "type": "object", "required": [ "id", "type", "created_at", "data" ], "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "order.created", "order.updated", "invoice.issued", "payment.recorded", "invoice.paid", "result.published", "endpoint.test" ] }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "order_id": { "type": "string", "nullable": true }, "status": { "$ref": "#/components/schemas/OrderStatus" }, "invoice_id": { "type": "string", "nullable": true }, "result_id": { "type": "string", "nullable": true }, "endpoint_id": { "type": "string" }, "links": { "type": "object" } } } } } } } }