{ "openapi": "3.0.0", "info": { "title": "API de MedineTech — sistema administrativo y contable", "description": "API REST del sistema administrativo y contable de MedineTech. Guía para integradores: [medine.tech/desarrolladores](https://medine.tech/desarrolladores).\n\n**Autenticación.** Envía `Authorization: Bearer ` y `Accept: application/json`. Un administrador crea la API key en Configuración de la compañía › API Keys. La clave se muestra una sola vez, queda ligada a quien la crea y a una sola empresa, y actúa con los permisos vigentes de esa persona. Una API key de solo lectura recibe 403 en toda operación que modifica datos. Las operaciones que solo admiten `cookieAuth` son exclusivas de la aplicación web y responden 403 a una API key.\n\n**Empresa.** Las operaciones están bajo `/api/backoffice/{tenant}/`: `{tenant}` es el identificador (UUID) de la empresa, el mismo que aparece en la dirección `https://erp.medine.tech/{tenant}/…`. Una API key usada con otra empresa recibe 404.\n\n**Vitrina.** Las operaciones bajo `/api/storefront/` usan una Clave de Vitrina (`mtsk_…`) emitida para un canal de venta, nunca una API key.\n\n**Errores.** 401 credencial ausente, inválida, vencida o revocada · 402 la suscripción o la titularidad de la empresa no permiten la operación · 403 sin permiso, API key de solo lectura u operación exclusiva de la aplicación web · 404 recurso o empresa inexistente o ajena · 409 conflicto con el estado actual (recurso duplicado, identificador ya usado, límite contratado o estado que no lo permite) o correo del titular sin verificar (`status: email_not_verified`) · 422 datos inválidos · 429 límite de peticiones, solo donde la operación lo aplica.\n\n**Antes de probar.** «Try it out» se ejecuta en producción sobre los datos reales de tu empresa: explora con una API key de solo lectura. Identifica tu integración con un `User-Agent` propio; la red de borde puede rechazar con 403 `Error code: 1010` las firmas de cliente genéricas.", "contact": { "name": "MedineTech", "url": "https://medine.tech/desarrolladores", "email": "customers@medine.tech" }, "version": "1.0.0" }, "servers": [ { "url": "https://erp-backend.medine.tech", "description": "Producción" } ], "paths": { "/api/backoffice/{tenant}/assistant/action-proposals/{id}/approval": { "post": { "tags": [ "Assistant - Action Proposals" ], "summary": "Approve an action proposal", "description": "Session only. Records Aprobación for an owned proposed ActionProposal. Idempotent when already approved. Expired, rejected, or non-pending rows answer 409.", "operationId": "41ef72a89639272c5c0dc14ee9099008", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Approved action proposal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionProposalResponse" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Session authentication required" }, "404": { "description": "Not found, foreign owner, other company, or assistant disabled", "content": { "application/json": { "schema": { "oneOf": [ { "required": [ "title", "status", "detail", "error_code" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer", "example": 404 }, "detail": { "type": "string" }, "error_code": { "type": "string", "example": "action_proposal_not_found" }, "errors": { "type": "object", "nullable": true } }, "type": "object" }, { "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Recurso no encontrado" } }, "type": "object" } ] } } } }, "409": { "description": "Lifecycle refusal", "content": { "application/json": { "schema": { "required": [ "title", "status", "detail", "error_code" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer", "example": 409 }, "detail": { "type": "string" }, "error_code": { "type": "string", "enum": [ "action_proposal_expired", "action_proposal_rejected", "action_proposal_not_pending" ] }, "errors": { "type": "object", "nullable": true } }, "type": "object" } } } }, "429": { "description": "Rate limited" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "cookieAuth": [] } ] } }, "/api/backoffice/{tenant}/assistant/action-proposals/{id}": { "get": { "tags": [ "Assistant - Action Proposals" ], "summary": "Get an action proposal", "description": "Session only. Returns an ActionProposal owned by the session user in the tenant company. Foreign owners, other companies, and missing ids answer 404.", "operationId": "668850288927fd3cbaad9eba24f7aa44", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Action proposal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionProposalResponse" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Session authentication required" }, "404": { "description": "Not found, foreign owner, other company, or assistant disabled", "content": { "application/json": { "schema": { "oneOf": [ { "required": [ "title", "status", "detail", "error_code" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer", "example": 404 }, "detail": { "type": "string" }, "error_code": { "type": "string", "example": "action_proposal_not_found" }, "errors": { "type": "object", "nullable": true } }, "type": "object" }, { "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Recurso no encontrado" } }, "type": "object" } ] } } } }, "429": { "description": "Rate limited" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "cookieAuth": [] } ] } }, "/api/backoffice/{tenant}/assistant/action-proposals/{id}/rejection": { "post": { "tags": [ "Assistant - Action Proposals" ], "summary": "Reject an action proposal", "description": "Session only. Rejects an owned proposed ActionProposal. Idempotent when already rejected. Approved or later statuses answer 409 not_pending; expired rows answer 409 expired.", "operationId": "1c6e71448baecffedd73272a06e42202", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Rejected action proposal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionProposalResponse" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Session authentication required" }, "404": { "description": "Not found, foreign owner, other company, or assistant disabled", "content": { "application/json": { "schema": { "oneOf": [ { "required": [ "title", "status", "detail", "error_code" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer", "example": 404 }, "detail": { "type": "string" }, "error_code": { "type": "string", "example": "action_proposal_not_found" }, "errors": { "type": "object", "nullable": true } }, "type": "object" }, { "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Recurso no encontrado" } }, "type": "object" } ] } } } }, "409": { "description": "Lifecycle refusal", "content": { "application/json": { "schema": { "required": [ "title", "status", "detail", "error_code" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer", "example": 409 }, "detail": { "type": "string" }, "error_code": { "type": "string", "enum": [ "action_proposal_not_pending", "action_proposal_expired" ] }, "errors": { "type": "object", "nullable": true } }, "type": "object" } } } }, "429": { "description": "Rate limited" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "cookieAuth": [] } ] } }, "/api/backoffice/{tenant}/assistant/attachments/{id}/download": { "get": { "tags": [ "Assistant - Attachments" ], "summary": "Get a temporary download URL for a staged assistant attachment", "description": "Session only. Issues a temporary download URL for an Adjunto del Asistente owned by the session user. Purged attachments answer 410; foreign or missing answer 404.", "operationId": "c981a2122f6e1ba03514fc1ccbb66c18", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Temporary download URL", "content": { "application/json": { "schema": { "required": [ "url", "expires_at" ], "properties": { "url": { "type": "string", "format": "uri" }, "expires_at": { "type": "string", "format": "date-time" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Session authentication required" }, "404": { "description": "Not found, foreign owner, or assistant disabled" }, "410": { "description": "assistant_attachment_purged", "content": { "application/json": { "schema": { "required": [ "title", "status", "detail", "error_code" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer", "example": 410 }, "detail": { "type": "string" }, "error_code": { "type": "string", "example": "assistant_attachment_purged" } }, "type": "object" } } } }, "429": { "description": "Rate limited" }, "503": { "description": "assistant_attachment_storage_unavailable" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "cookieAuth": [] } ] } }, "/api/backoffice/{tenant}/assistant/attachments/{id}": { "get": { "tags": [ "Assistant - Attachments" ], "summary": "Get staged assistant attachment metadata", "description": "Session only. Returns metadata for an Adjunto del Asistente owned by the session user. Foreign or missing ids answer 404. Purged rows still return 200 with purged: true.", "operationId": "767da05b5b8d79cad77827291aa9967f", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Attachment metadata", "content": { "application/json": { "schema": { "required": [ "id", "original_name", "mime_type", "size_bytes", "created_at", "purged" ], "properties": { "id": { "type": "string", "format": "uuid" }, "original_name": { "type": "string" }, "mime_type": { "type": "string" }, "size_bytes": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "purged": { "type": "boolean" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Session authentication required" }, "404": { "description": "Not found, foreign owner, or assistant disabled" }, "429": { "description": "Rate limited" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "cookieAuth": [] } ] } }, "/api/backoffice/{tenant}/assistant/attachments": { "post": { "tags": [ "Assistant - Attachments" ], "summary": "Upload a staged assistant attachment", "description": "Session only. Stages a private Adjunto del Asistente (image/PDF ≤15 MiB) under assistant/{company}/{user}/. Same id+sha256 returns 200; a conflicting payload returns 409. Requires the company assistant to be enabled.", "operationId": "f47a86309267aedca2e49c125c56be2f", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "id", "file" ], "properties": { "id": { "description": "Client-supplied UUIDv7", "type": "string", "format": "uuid", "example": "0190b7a0-1111-7222-8333-444455556666" }, "file": { "description": "Maximum 15 MiB. Matching MIME and extension: JPG/JPEG, PNG, WEBP or PDF.", "type": "string", "format": "binary" } }, "type": "object" } } } }, "responses": { "201": { "description": "Attachment staged", "content": { "application/json": { "schema": { "required": [ "id", "original_name", "mime_type", "size_bytes", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "original_name": { "type": "string" }, "mime_type": { "type": "string" }, "size_bytes": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" } } } }, "200": { "description": "Idempotent replay of the same id and content", "content": { "application/json": { "schema": { "required": [ "id", "original_name", "mime_type", "size_bytes", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "original_name": { "type": "string" }, "mime_type": { "type": "string" }, "size_bytes": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Session authentication required" }, "404": { "description": "Company missing or assistant disabled" }, "409": { "description": "assistant_attachment_id_conflict", "content": { "application/json": { "schema": { "required": [ "title", "status", "detail", "error_code" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer", "example": 409 }, "detail": { "type": "string" }, "error_code": { "type": "string", "example": "assistant_attachment_id_conflict" } }, "type": "object" } } } }, "422": { "description": "Field validation (error_code null) or assistant_attachment_type_not_allowed / assistant_attachment_too_large", "content": { "application/json": { "schema": { "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string" }, "error_code": { "type": "string", "nullable": true, "enum": [ "assistant_attachment_type_not_allowed", "assistant_attachment_too_large" ] }, "errors": { "type": "object", "nullable": true } }, "type": "object" } } } }, "429": { "description": "More than 30 uploads in a minute" }, "503": { "description": "assistant_attachment_storage_unavailable" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "cookieAuth": [] } ] } }, "/api/backoffice/{tenant}/assistant/availability": { "get": { "tags": [ "Assistant - Tokens" ], "summary": "Read Asistente availability for the session company", "description": "Session members can read effective company Asistente availability without an administrator permission. Free returns enabled false even when the stored flag is on; Pro and managed companies require the flag. Channel configuration does not determine availability.", "operationId": "371d5a01fa36a544596618a1440490c6", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Effective company Asistente availability, including false for Free or when switched off", "headers": { "Cache-Control": { "description": "Never cache this private company flag", "schema": { "type": "string", "example": "no-store, private" } } }, "content": { "application/json": { "schema": { "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean", "example": true } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "403": { "description": "Session authentication required or company membership denied", "content": { "application/json": { "schema": { "anyOf": [ { "required": [ "title", "status", "detail" ], "properties": { "title": { "type": "string", "example": "Forbidden" }, "status": { "type": "integer", "example": 403 }, "detail": { "type": "string", "example": "This operation requires session authentication." } }, "type": "object" }, { "required": [ "title", "status", "detail", "reason" ], "properties": { "title": { "type": "string", "example": "Forbidden" }, "status": { "type": "integer", "example": 403 }, "detail": { "type": "string", "example": "You do not have access to this tenant" }, "reason": { "type": "string", "example": "DENIED_NO_MEMBERSHIP" } }, "type": "object" } ] } } } }, "404": { "description": "Company not found or not accessible to the session", "content": { "application/json": { "schema": { "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Recurso no encontrado" } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "cookieAuth": [] } ] } }, "/api/backoffice/{tenant}/assistant/channel-tokens": { "post": { "tags": [ "Assistant - Tokens" ], "summary": "Issue a channel token for the Asistente app from the session", "description": "Session only. The token authenticates the Asistente chat for the session user in this company for 15 minutes. It never reaches MCP: only the Asistente app, authenticated as a confidential client, can exchange it for a delegated MCP token at POST /api/assistant/token. Request a new one before it expires.", "operationId": "1192ddb7a8a909d047e04f59b0e3dbc4", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Channel token issued; the plain text is returned once", "headers": { "Cache-Control": { "description": "Always no-store", "schema": { "type": "string", "example": "no-store, private" } }, "Pragma": { "description": "Always no-cache", "schema": { "type": "string", "example": "no-cache" } } }, "content": { "application/json": { "schema": { "required": [ "token", "expires_in", "audience" ], "properties": { "token": { "description": "One-time plaintext channel token", "type": "string", "example": "17|Qm9sZXRvLWRlLWNhbmFs" }, "expires_in": { "description": "Lifetime in seconds", "type": "integer", "example": 900 }, "audience": { "description": "The Asistente channel audience the token is bound to", "type": "string", "example": "https://asistente.medine.tech" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "403": { "description": "A bearer token instead of a session, a read-only API key, or no membership in the company", "content": { "application/json": { "schema": { "oneOf": [ { "required": [ "title", "status", "detail" ], "properties": { "title": { "type": "string", "example": "Forbidden" }, "status": { "type": "integer", "example": 403 }, "detail": { "type": "string", "example": "This operation requires session authentication." } }, "type": "object" }, { "required": [ "title", "status", "detail", "reason" ], "properties": { "title": { "type": "string", "example": "Forbidden" }, "status": { "type": "integer", "example": 403 }, "detail": { "type": "string", "example": "You do not have access to this tenant" }, "reason": { "type": "string", "example": "DENIED_NO_MEMBERSHIP" } }, "type": "object" } ] } } } }, "404": { "description": "The company does not exist, is not the session's, or has the assistant switched off", "content": { "application/json": { "schema": { "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Recurso no encontrado" } }, "type": "object" } } } }, "429": { "description": "More than 30 channel tokens requested in a minute", "headers": { "Retry-After": { "description": "Seconds until the next request is allowed", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "type": "object" } } } }, "503": { "description": "assistant_channel_not_configured: the environment has no channel audience", "content": { "application/json": { "schema": { "required": [ "title", "status", "detail", "error_code" ], "properties": { "title": { "type": "string", "example": "Service Unavailable" }, "status": { "type": "integer", "example": 503 }, "detail": { "type": "string", "example": "La audiencia del canal del Asistente no está configurada." }, "error_code": { "type": "string", "enum": [ "assistant_channel_not_configured" ] }, "errors": { "type": "object", "nullable": true } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "cookieAuth": [] } ] } }, "/api/assistant/token": { "post": { "tags": [ "Assistant - Tokens" ], "summary": "Exchange a channel token or a contact key for a delegated MCP token (RFC 8693)", "description": "Only registered agent clients, authenticated with HTTP Basic, may call it. The backoffice-assistant client trades the channel token of the current Asistente request for a 15-minute token bound to that person's company MCP URL. The whatsapp-agent client trades the opaque key of the turn's verified contact for a 15-minute mcp:public token of the WhatsApp service principal, bound to the MCP URL of the configured company; the token carries the contact key, the response never does. The fields are read from the body only, never from the query string. Every error uses the RFC 6749 section 5.2 body and never says why a token was refused.", "operationId": "ad650bd234dee338c6b0c9a64e66977e", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "description": "One shape per client: backoffice-assistant sends a channel token, whatsapp-agent sends a contact key. A body that carries both subjects is an invalid_grant.", "oneOf": [ { "title": "Channel token (backoffice-assistant)", "required": [ "grant_type", "subject_token", "subject_token_type", "resource", "scope" ], "properties": { "grant_type": { "type": "string", "enum": [ "urn:ietf:params:oauth:grant-type:token-exchange" ] }, "subject_token": { "description": "The channel token of the current request", "type": "string", "example": "17|Qm9sZXRvLWRlLWNhbmFs" }, "subject_token_type": { "type": "string", "enum": [ "urn:medinetech:params:token-type:assistant-channel" ] }, "resource": { "description": "The MCP URL of the person's company: APP_URL/api/backoffice/{company}/mcp, lowercase company, no trailing slash.", "type": "string", "format": "uri", "example": "https://erp-backend.medine.tech/api/backoffice/0199a3f6-1d1e-7a2b-9c3d-4e5f60718211/mcp" }, "scope": { "description": "Space-separated: mcp:read, or mcp:read mcp:write (mcp:write implies mcp:read).", "type": "string", "example": "mcp:read" } }, "type": "object", "additionalProperties": false }, { "title": "Contact key (whatsapp-agent)", "required": [ "grant_type", "subject_contact", "resource", "scope" ], "properties": { "grant_type": { "type": "string", "enum": [ "urn:ietf:params:oauth:grant-type:token-exchange" ] }, "subject_contact": { "description": "The opaque key of the turn's verified contact, never a phone number: valid UTF-8 without control characters", "type": "string", "example": "c-123", "maxLength": 128, "minLength": 1 }, "resource": { "description": "The MCP URL of the configured company: APP_URL/api/backoffice/{company}/mcp, lowercase company, no trailing slash.", "type": "string", "format": "uri", "example": "https://erp-backend.medine.tech/api/backoffice/0199a3f6-1d1e-7a2b-9c3d-4e5f60718211/mcp" }, "scope": { "description": "Only mcp:public.", "type": "string", "example": "mcp:public", "enum": [ "mcp:public" ] } }, "type": "object", "additionalProperties": false } ] } }, "application/json": { "schema": { "description": "One shape per client: backoffice-assistant sends a channel token, whatsapp-agent sends a contact key. A body that carries both subjects is an invalid_grant.", "oneOf": [ { "title": "Channel token (backoffice-assistant)", "required": [ "grant_type", "subject_token", "subject_token_type", "resource", "scope" ], "properties": { "grant_type": { "type": "string", "enum": [ "urn:ietf:params:oauth:grant-type:token-exchange" ] }, "subject_token": { "description": "The channel token of the current request", "type": "string", "example": "17|Qm9sZXRvLWRlLWNhbmFs" }, "subject_token_type": { "type": "string", "enum": [ "urn:medinetech:params:token-type:assistant-channel" ] }, "resource": { "description": "The MCP URL of the person's company: APP_URL/api/backoffice/{company}/mcp, lowercase company, no trailing slash.", "type": "string", "format": "uri", "example": "https://erp-backend.medine.tech/api/backoffice/0199a3f6-1d1e-7a2b-9c3d-4e5f60718211/mcp" }, "scope": { "description": "Space-separated: mcp:read, or mcp:read mcp:write (mcp:write implies mcp:read).", "type": "string", "example": "mcp:read" } }, "type": "object", "additionalProperties": false }, { "title": "Contact key (whatsapp-agent)", "required": [ "grant_type", "subject_contact", "resource", "scope" ], "properties": { "grant_type": { "type": "string", "enum": [ "urn:ietf:params:oauth:grant-type:token-exchange" ] }, "subject_contact": { "description": "The opaque key of the turn's verified contact, never a phone number: valid UTF-8 without control characters", "type": "string", "example": "c-123", "maxLength": 128, "minLength": 1 }, "resource": { "description": "The MCP URL of the configured company: APP_URL/api/backoffice/{company}/mcp, lowercase company, no trailing slash.", "type": "string", "format": "uri", "example": "https://erp-backend.medine.tech/api/backoffice/0199a3f6-1d1e-7a2b-9c3d-4e5f60718211/mcp" }, "scope": { "description": "Only mcp:public.", "type": "string", "example": "mcp:public", "enum": [ "mcp:public" ] } }, "type": "object", "additionalProperties": false } ] } } } }, "responses": { "200": { "description": "Delegated MCP token issued", "headers": { "Cache-Control": { "description": "Always no-store", "schema": { "type": "string", "example": "no-store, private" } }, "Pragma": { "description": "Always no-cache", "schema": { "type": "string", "example": "no-cache" } } }, "content": { "application/json": { "schema": { "required": [ "access_token", "issued_token_type", "token_type", "expires_in", "scope", "resource", "subject" ], "properties": { "access_token": { "type": "string", "example": "18|RGVsZWdhZG8tbWNw" }, "issued_token_type": { "type": "string", "enum": [ "urn:ietf:params:oauth:token-type:access_token" ] }, "token_type": { "type": "string", "enum": [ "Bearer" ] }, "expires_in": { "type": "integer", "example": 900 }, "scope": { "description": "The canonical abilities granted, space-separated", "type": "string", "example": "mcp:read mcp:write" }, "resource": { "type": "string", "format": "uri", "example": "https://erp-backend.medine.tech/api/backoffice/0199a3f6-1d1e-7a2b-9c3d-4e5f60718211/mcp" }, "subject": { "required": [ "user_id", "company_id" ], "properties": { "user_id": { "type": "integer", "example": 42 }, "company_id": { "type": "string", "format": "uuid", "example": "0199a3f6-1d1e-7a2b-9c3d-4e5f60718211" } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "invalid_request (a missing field, a subject_token or subject_token_type that is not a string, or an unsupported subject_token_type), unsupported_grant_type, invalid_grant (the channel token is unknown, expired, revoked or of another audience; the contact key is missing, not a string, longer than 128 characters, not UTF-8 or has a control character; the client sent a field of the other client's subject, whatever its type; the WhatsApp service principal is not configured; the principal left the company; or the company switched the assistant off), invalid_target (the resource is not that company's MCP URL) or invalid_scope (a scope the client may not be granted)", "headers": { "Cache-Control": { "description": "Always no-store", "schema": { "type": "string", "example": "no-store, private" } } }, "content": { "application/json": { "schema": { "required": [ "error", "error_description" ], "properties": { "error": { "type": "string", "enum": [ "invalid_request", "unsupported_grant_type", "invalid_grant", "invalid_target", "invalid_scope" ] }, "error_description": { "type": "string", "example": "The subject token is not valid." } }, "type": "object" } } } }, "401": { "description": "invalid_client: missing Basic credentials, an unknown client, a client without configured secret hashes, or a wrong secret", "headers": { "WWW-Authenticate": { "description": "Always Basic realm=assistant", "schema": { "type": "string", "example": "Basic realm=\"assistant\"" } }, "Cache-Control": { "description": "Always no-store", "schema": { "type": "string", "example": "no-store, private" } } }, "content": { "application/json": { "schema": { "required": [ "error", "error_description" ], "properties": { "error": { "type": "string", "enum": [ "invalid_client" ] }, "error_description": { "type": "string", "example": "Client authentication failed." } }, "type": "object" } } } }, "429": { "description": "More than 60 counted requests of one client in a minute (failed client authentications never count), or a failed client authentication from an IP that already failed 20 times that minute. A correctly authenticated client is never refused because of its IP.", "headers": { "Retry-After": { "description": "Seconds until the next request is allowed", "schema": { "type": "integer" } }, "Cache-Control": { "description": "no-store on the answer to a failed client authentication", "schema": { "type": "string", "example": "no-store, private" } } }, "content": { "application/json": { "schema": { "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "type": "object" } } } } }, "security": [ { "assistantClientBasic": [] } ] } }, "/api/backoffice/{tenant}/assistant/tokens": { "delete": { "tags": [ "Assistant - Tokens" ], "summary": "Revoke the session user's channel and delegated tokens for this company", "description": "Deletes every audience-bound token (channel and MCP delegated tokens) the authenticated person holds for this company. API keys and login tokens are untouched. Works while the company has the assistant switched off.", "operationId": "c0663f0a214a8ca16d34b027f902bbde", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "The person's audience tokens for this company are revoked" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "403": { "description": "A bearer token instead of a session, or no membership in the company", "content": { "application/json": { "schema": { "oneOf": [ { "required": [ "title", "status", "detail" ], "properties": { "title": { "type": "string", "example": "Forbidden" }, "status": { "type": "integer", "example": 403 }, "detail": { "type": "string", "example": "This operation requires session authentication." } }, "type": "object" }, { "required": [ "title", "status", "detail", "reason" ], "properties": { "title": { "type": "string", "example": "Forbidden" }, "status": { "type": "integer", "example": 403 }, "detail": { "type": "string", "example": "You do not have access to this tenant" }, "reason": { "type": "string", "example": "DENIED_NO_MEMBERSHIP" } }, "type": "object" } ] } } } }, "404": { "description": "The company does not exist or is not the session's", "content": { "application/json": { "schema": { "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Recurso no encontrado" } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "cookieAuth": [] } ] } }, "/api/assistant/channel-tokens/introspection": { "post": { "tags": [ "Assistant - Tokens" ], "summary": "Introspect a channel token for the Asistente app", "description": "Only the backoffice-assistant client, authenticated with HTTP Basic, may call it; any other client, including whatsapp-agent, is refused before the request is read. It answers whether a Token de canal still opens the assistant, through the same checks as the token exchange, and never mints a token. An inactive answer is the same body whatever the reason: an unknown, revoked or expired token, a token of another audience or ability, a person who left the company, a company with the assistant switched off, or an unconfigured channel audience. The token travels in the JSON body only, never in the URL. It is a side-effect-free query, so it answers 200, not 201.", "operationId": "cdaa4e597bd3084c7d24716a91c67283", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "token" ], "properties": { "token": { "description": "The channel token to verify", "type": "string", "example": "17|Qm9sZXRvLWRlLWNhbmFs", "maxLength": 4096, "minLength": 1 } }, "type": "object", "additionalProperties": false } } } }, "responses": { "200": { "description": "Whether the channel token is active, with its person, company and expiry when it is", "headers": { "Cache-Control": { "description": "Always no-store", "schema": { "type": "string", "example": "no-store, private" } }, "Pragma": { "description": "Always no-cache", "schema": { "type": "string", "example": "no-cache" } } }, "content": { "application/json": { "schema": { "oneOf": [ { "title": "Active", "required": [ "active", "subject", "expiresAt", "displayName", "companyName" ], "properties": { "active": { "type": "boolean", "enum": [ true ] }, "displayName": { "description": "Session-known person name for in-memory pseudonymization; never put it in eve attributes or logs", "type": "string", "example": "José Pérez" }, "companyName": { "description": "Session-known Company name for pseudonymization", "type": "string", "example": "Comercial Ávila" }, "subject": { "required": [ "userId", "companyId" ], "properties": { "userId": { "type": "integer", "example": 42 }, "companyId": { "type": "string", "format": "uuid", "example": "0199a3f6-1d1e-7a2b-9c3d-4e5f60718211" } }, "type": "object", "additionalProperties": false }, "expiresAt": { "description": "The token's expiry, in UTC with second precision", "type": "string", "format": "date-time", "example": "2026-10-02T12:15:00Z" } }, "type": "object", "additionalProperties": false }, { "title": "Inactive", "required": [ "active" ], "properties": { "active": { "type": "boolean", "enum": [ false ] } }, "type": "object", "additionalProperties": false } ] } } } }, "401": { "description": "invalid_client, answered by the route gate before the request is read: missing Basic credentials, an unknown client, a client without configured secret hashes, a wrong secret, or an authentic client other than backoffice-assistant", "headers": { "WWW-Authenticate": { "description": "Always Basic realm=assistant", "schema": { "type": "string", "example": "Basic realm=\"assistant\"" } }, "Cache-Control": { "description": "Always no-store", "schema": { "type": "string", "example": "no-store, private" } }, "Pragma": { "description": "Always no-cache", "schema": { "type": "string", "example": "no-cache" } } }, "content": { "application/json": { "schema": { "required": [ "error", "error_description" ], "properties": { "error": { "type": "string", "enum": [ "invalid_client" ] }, "error_description": { "type": "string", "example": "Client authentication failed." } }, "type": "object" } } } }, "422": { "description": "channel_token_introspection_invalid: a body that is not a JSON object with only a token string of 1 to 4096 characters, or any query string", "headers": { "Cache-Control": { "description": "Always no-store", "schema": { "type": "string", "example": "no-store, private" } }, "Pragma": { "description": "Always no-cache", "schema": { "type": "string", "example": "no-cache" } } }, "content": { "application/json": { "schema": { "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string", "example": "La solicitud de introspección debe ser un cuerpo JSON con solo un token de texto de 1 a 4096 caracteres y sin parámetros de consulta." }, "error_code": { "type": "string", "enum": [ "channel_token_introspection_invalid" ] }, "errors": { "type": "object", "example": null, "nullable": true } }, "type": "object" } } } }, "429": { "description": "More than 600 counted requests of one client in a minute (failed client authentications never count), or a failed client authentication from an IP that already failed 20 times that minute. A correctly authenticated client is never refused because of its IP, and neither budget is shared with the token exchange.", "headers": { "Retry-After": { "description": "Seconds until the next request is allowed", "schema": { "type": "integer" } }, "Cache-Control": { "description": "Always no-store", "schema": { "type": "string", "example": "no-store, private" } }, "Pragma": { "description": "Always no-cache", "schema": { "type": "string", "example": "no-cache" } } }, "content": { "application/json": { "schema": { "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "type": "object" } } } } }, "security": [ { "assistantClientBasic": [] } ] } }, "/api/backoffice/{tenant}/assistant/usage/me": { "get": { "tags": [ "Assistant - Usage" ], "summary": "OwnUsageBudgetGet", "operationId": "4707fe5a57ae52cfb3ba981dfa4ec1e9", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Private own usage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OwnUsageBudget" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageBudgetError401" } } } }, "402": { "description": "Subscription access required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageBudgetError402" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageBudgetError403" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageBudgetError404" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageBudgetError422" } } } }, "503": { "description": "Usage unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageBudgetError503" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageBudgetError500" } } } } }, "security": [ { "cookieAuth": [] } ] } }, "/api/assistant/usage/admissions": { "post": { "tags": [ "Assistant Usage" ], "summary": "Admit one bounded model step", "description": "Service-only: Basic backoffice-assistant plus validated channel subject. Stable replay returns the original decision even after policy or month changes; changed execution or scope conflicts. An allow authorizes at most one inference; each later step needs a fresh attempt. Fail closed on uncertainty and retry the same identity.", "operationId": "cfe53033f3e266b138da488964987cb1", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageAdmissionInput" } } } }, "responses": { "200": { "description": "Immutable allow or block decision; no amounts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageAdmissionDecision" } } } }, "401": { "description": "Safe error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageBudgetError401" } } } }, "403": { "description": "Safe error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageBudgetError403" } } } }, "404": { "description": "Safe error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageBudgetError404" } } } }, "409": { "description": "Safe error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageAdmissionError409" } } } }, "422": { "description": "Safe error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageBudgetError422" } } } }, "429": { "description": "Authentication failure after 20 failures from an IP in 60 seconds. Valid authenticated requests bypass this response-only failure bucket; authentication work is still performed.", "headers": { "Retry-After": { "description": "Seconds until another authentication failure may return its original status", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageAdmissionError429" } } } }, "503": { "description": "Safe error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageBudgetError503" } } } }, "500": { "description": "Safe error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageBudgetError500" } } } } }, "security": [ { "assistantClientBasic": [] } ] } }, "/api/backoffice/{tenant}/assistant/usage/budgets/company-default": { "get": { "tags": [ "Assistant - Usage" ], "summary": "UsageCompanyBudgetGet", "operationId": "e49bde46c35afbdfd188a542dfbb8861", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Administrator configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageBudgetConfiguration" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageBudgetError401" } } } }, "402": { "description": "Subscription access required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageBudgetError402" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageBudgetError403" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageBudgetError404" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageBudgetError422" } } } }, "503": { "description": "Usage unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageBudgetError503" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageBudgetError500" } } } } }, "security": [ { "cookieAuth": [] } ] }, "put": { "tags": [ "Assistant - Usage" ], "summary": "UsageCompanyBudgetPut", "operationId": "9989415fc34013e535175cab8fa09125", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageBudgetInput" } } } }, "responses": { "200": { "description": "Administrator configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageBudgetConfiguration" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageBudgetError401" } } } }, "402": { "description": "Subscription access required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageBudgetError402" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageBudgetError403" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageBudgetError404" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageBudgetError422" } } } }, "503": { "description": "Usage unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageBudgetError503" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageBudgetError500" } } } } }, "security": [ { "cookieAuth": [] } ] } }, "/api/assistant/usage/events": { "post": { "tags": [ "Assistant Usage" ], "summary": "Commit a private service-owned usage operation", "operationId": "dbdeb7498e1df4b2f8e286ead4769692", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssistantUsageEvent" } } } }, "responses": { "201": { "description": "Operation committed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssistantUsageReceipt" } } } }, "200": { "description": "Original committed receipt replayed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssistantUsageReceipt" } } } }, "401": { "description": "Confidential-client credentials required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageBudgetError401" } } } }, "403": { "description": "Attempt not owned or admitted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageBudgetError403" } } } }, "409": { "description": "Changed operation or contradictory terminal state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageAdmissionError409" } } } }, "422": { "description": "Invalid event", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageBudgetError422" } } } }, "429": { "description": "Repeated authentication failures only; authenticated owned settlement is never throttled", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageAdmissionError429" } } } }, "503": { "description": "Accounting unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageBudgetError503" } } } }, "500": { "description": "Stored accounting integrity failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageBudgetError500" } } } } }, "security": [ { "assistantClientBasic": [] } ] } }, "/api/backoffice/{tenant}/assistant/usage/budgets/members/{personId}": { "get": { "tags": [ "Assistant - Usage" ], "summary": "UsageMemberBudgetGet", "operationId": "c6022ced1f149fea707d4777bf714587", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "personId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" } } ], "responses": { "200": { "description": "Administrator configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageBudgetConfiguration" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageBudgetError401" } } } }, "402": { "description": "Subscription access required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageBudgetError402" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageBudgetError403" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageBudgetError404" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageBudgetError422" } } } }, "503": { "description": "Usage unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageBudgetError503" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageBudgetError500" } } } } }, "security": [ { "cookieAuth": [] } ] }, "put": { "tags": [ "Assistant - Usage" ], "summary": "UsageMemberBudgetPut", "operationId": "8e4d955b0f900bc08c614461207037a1", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "personId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageBudgetInput" } } } }, "responses": { "200": { "description": "Administrator configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageBudgetConfiguration" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageBudgetError401" } } } }, "402": { "description": "Subscription access required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageBudgetError402" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageBudgetError403" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageBudgetError404" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageBudgetError422" } } } }, "503": { "description": "Usage unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageBudgetError503" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageBudgetError500" } } } } }, "security": [ { "cookieAuth": [] } ] }, "delete": { "tags": [ "Assistant - Usage" ], "summary": "UsageMemberBudgetDelete", "operationId": "a7e0612d010fb78a528581abfdde57b6", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "personId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" } } ], "responses": { "204": { "description": "Override removed" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageBudgetError401" } } } }, "402": { "description": "Subscription access required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageBudgetError402" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageBudgetError403" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageBudgetError404" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageBudgetError422" } } } }, "503": { "description": "Usage unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageBudgetError503" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageBudgetError500" } } } } }, "security": [ { "cookieAuth": [] } ] } }, "/api/backoffice/{tenant}/assistant/usage/report": { "get": { "tags": [ "Assistant - Usage" ], "summary": "UsageSpendReportGet", "description": "Company-administrator AI spend report by person, function or model for a Caracas month. Requires company admin and backoffice.assistant.usage.view.", "operationId": "c7b8577e4affef1e615604d64da8ddbf", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "month", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[0-9]{4}-(0[1-9]|1[0-2])$" } }, { "name": "grouping", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "person", "function", "model" ] } }, { "name": "person_id", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[0-9]+$" } }, { "name": "function", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "in_app", "whatsapp", "receipt_extraction", "system_one" ] } }, { "name": "model", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 128, "minLength": 1 } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "Administrator spend report", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssistantUsageSpendReport" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageBudgetError401" } } } }, "402": { "description": "Subscription access required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageBudgetError402" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageBudgetError403" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageBudgetError404" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageBudgetError422" } } } }, "503": { "description": "Usage report unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageBudgetError503" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageBudgetError500" } } } } }, "security": [ { "cookieAuth": [] } ] } }, "/api/backoffice/{tenant}/assistant/usage/warnings/claim": { "post": { "tags": [ "Assistant - Usage" ], "summary": "UsageWarningClaimPost", "operationId": "944b54433b750a2501d768a4929daf0e", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false } } } }, "responses": { "200": { "description": "Highest eligible warning claim for this period", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageWarningClaimResult" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageBudgetError401" } } } }, "402": { "description": "Subscription access required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageBudgetError402" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageBudgetError403" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageBudgetError404" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageBudgetError422" } } } }, "503": { "description": "Usage unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageBudgetError503" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageBudgetError500" } } } } }, "security": [ { "cookieAuth": [] } ] } }, "/api/login": { "post": { "tags": [ "Authentication" ], "summary": "Authenticate user (PAT-mode returns token; cookie-mode sets httpOnly session cookie)", "operationId": "bc76a9d52929cab7a147ca7b5c527430", "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "email": { "type": "string", "example": "user@example.com" }, "password": { "type": "string", "example": "password" } }, "type": "object" } } } }, "responses": { "200": { "description": "Successful authentication. PAT-mode includes `token`; cookie-mode omits it.", "content": { "application/json": { "schema": { "properties": { "token": { "description": "Present in PAT-mode only", "type": "string", "example": "your_token_here", "nullable": true }, "user_id": { "description": "Present in PAT-mode only", "type": "integer", "example": 1, "nullable": true }, "default_company_id": { "type": "string", "example": "123e4567-e89b-12d3-a456-426614174000" }, "needs_email_verification": { "type": "boolean", "example": false }, "permissions": { "type": "array", "items": { "type": "string" } }, "authorization": { "description": "Unified authorization read model (MER-641). Omitted if the fetcher cannot resolve the user's membership.", "properties": { "user_id": { "type": "integer" }, "company_id": { "type": "string" }, "permissions": { "type": "array", "items": { "type": "string" } }, "role_codes": { "type": "array", "items": { "type": "string" } }, "is_admin": { "type": "boolean" }, "admin_reason": { "type": "string", "enum": [ "ADMIN_BYPASS", "EXPLICIT_PERMISSION", "DENIED_NO_PERMISSION", "DENIED_TENANT_MISMATCH", "DENIED_NO_MEMBERSHIP" ] } }, "type": "object" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Validation Error" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string", "example": "The given data was invalid." }, "errors": { "type": "object" } }, "type": "object" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unauthorized" }, "status": { "type": "integer", "example": 401 }, "detail": { "type": "string", "example": "Invalid credentials" } }, "type": "object" } } } }, "403": { "description": "Email not verified", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" }, "needs_email_verification": { "type": "boolean", "example": true } }, "type": "object" } } } } } } }, "/api/logout": { "post": { "tags": [ "Authentication" ], "summary": "Logout user (PAT-mode revokes token; cookie-mode invalidates session) and revokes the user's audience tokens", "operationId": "0ab4e3cf7bc4f7ec81b48f7928c7de7c", "responses": { "200": { "description": "Successful logout", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Logged out successfully" } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unauthorized" }, "status": { "type": "integer", "example": 401 }, "detail": { "type": "string", "example": "Unauthenticated" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/auth/companies": { "get": { "tags": [ "Auth - Companies" ], "summary": "Retrieve a list of companies", "description": "Returns a paginated list of companies for authorized users. Accepts optional query parameters for filtering.", "operationId": "ab862e795e9632886b7cc0dec86a6ae9", "parameters": [ { "name": "page", "in": "query", "description": "Page number for pagination", "required": false, "schema": { "type": "integer", "example": 1 } }, { "name": "per_page", "in": "query", "description": "Number of entries per page", "required": false, "schema": { "type": "integer", "example": 10 } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "items": { "type": "array", "items": { "properties": { "id": { "type": "string", "example": "1" }, "name": { "type": "string", "example": "Company 1" } }, "type": "object" } }, "total": { "type": "integer", "example": 100 }, "per_page": { "type": "integer", "example": 10 }, "current_page": { "type": "integer", "example": 1 } }, "type": "object" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unauthorized" }, "status": { "type": "integer", "example": 403 }, "detail": { "type": "string", "example": "You do not have permission to view this resource." } }, "type": "object" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Internal Server Error" }, "status": { "type": "integer", "example": 500 }, "detail": { "type": "string", "example": "An unexpected error occurred" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/auth/company-access": { "get": { "tags": [ "Auth - Companies" ], "summary": "Where the authenticated user may go, and where they should land", "description": "Returns every company the authenticated user is a member of, plus the company their session should open in. The stored `default_company_id` preference is honoured only while it is still an accessible company; otherwise the first accessible company is chosen. Both are null/empty when the user has no memberships.", "operationId": "aacfe2286607e7cead99d85d20e010c1", "responses": { "200": { "description": "The user's company access", "content": { "application/json": { "schema": { "properties": { "landingCompanyId": { "type": "string", "example": "9f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f", "nullable": true }, "companies": { "type": "array", "items": { "properties": { "id": { "type": "string", "example": "9f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f" }, "name": { "type": "string", "example": "Mueblería Lucía" } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unauthorized" }, "status": { "type": "integer", "example": 401 }, "detail": { "type": "string", "example": "Authentication required" } }, "type": "object" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Internal Server Error" }, "status": { "type": "integer", "example": 500 }, "detail": { "type": "string", "example": "An unexpected error occurred" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/email-verification/code": { "post": { "tags": [ "Authentication" ], "summary": "Verify a six-digit code and start a SPA cookie session", "operationId": "20aaa698e2f4ee1d6b5664451f3b9e7c", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "email", "code" ], "properties": { "email": { "type": "string", "format": "email" }, "code": { "type": "string", "pattern": "^[0-9]{6}$", "example": "012345" } }, "type": "object" } } } }, "responses": { "200": { "description": "Verified; authenticated session cookie regenerated. No personal access token is issued.", "content": { "application/json": { "schema": { "required": [ "default_company_id", "needs_email_verification", "user", "permissions" ], "properties": { "default_company_id": { "type": "string", "format": "uuid" }, "needs_email_verification": { "type": "boolean", "example": false }, "user": { "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "defaultCompanyId": { "type": "string" } }, "type": "object" }, "permissions": { "type": "array", "items": { "type": "string" } }, "authorization": { "type": "object" } }, "type": "object" } } } }, "422": { "description": "All invalid codes and unknown identities share this Problem envelope; malformed email uses field validation.", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string", "example": "Código inválido o vencido" }, "error_code": { "type": "string", "example": "email_verification_code_invalid", "nullable": true }, "errors": { "type": "object", "nullable": true } }, "type": "object" } } } }, "429": { "description": "30 requests per minute per IP; 10 per canonical email.", "headers": { "Retry-After": { "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailVerificationRateLimitProblem" } } } }, "503": { "description": "A started SPA session is required; code remains usable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailVerificationAvailabilityProblem" } } } }, "419": { "description": "Native CSRF middleware response for a stateful request with invalid CSRF credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailVerificationMiddlewareError" } } } } } } }, "/api/email/verification-notification": { "post": { "tags": [ "Authentication" ], "summary": "Send a new email verification notification", "operationId": "21ff3f9f9b9e1407909089f864312e1c", "responses": { "200": { "description": "Verification link sent", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "verification-link-sent" } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unauthorized" }, "status": { "type": "integer", "example": 401 }, "detail": { "type": "string", "example": "Unauthenticated" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/reset-password": { "post": { "tags": [ "Authentication" ], "summary": "Reset user password with token", "operationId": "28566bf52aa8f35c19b304b2c2be3829", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "token", "email", "password", "password_confirmation" ], "properties": { "token": { "type": "string", "example": "reset-token" }, "email": { "type": "string", "format": "email", "example": "user@example.com" }, "password": { "type": "string", "example": "new-password" }, "password_confirmation": { "type": "string", "example": "new-password" } }, "type": "object" } } } }, "responses": { "200": { "description": "Password reset successful", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "Your password has been reset!" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Validation Error" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string", "example": "The given data was invalid." }, "errors": { "type": "object" } }, "type": "object" } } } } } } }, "/api/forgot-password": { "post": { "tags": [ "Authentication" ], "summary": "Send a password reset link to the given email", "operationId": "e6a36e6e48542536284f7f26f6cc4d7f", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "example": "user@example.com" } }, "type": "object" } } } }, "responses": { "200": { "description": "Password reset link sent", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "We have emailed your password reset link!" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Validation Error" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string", "example": "The given data was invalid." }, "errors": { "type": "object" } }, "type": "object" } } } } } } }, "/api/email-verification": { "post": { "tags": [ "Authentication" ], "summary": "Resend a verification code", "operationId": "8f87a0279fb3c4cabe0f2f7a9493a3f6", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "email", "turnstileToken" ], "properties": { "email": { "type": "string", "format": "email" }, "turnstileToken": { "type": "string", "maxLength": 2048 } }, "type": "object" } } } }, "responses": { "200": { "description": "Same response regardless of identity eligibility or delivery failure.", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Si el correo puede verificarse, recibirás un código de verificación." } }, "type": "object" } } } }, "422": { "description": "Invalid email or Turnstile token; controller Problem envelope with field errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailVerificationValidationProblem" } } } }, "429": { "description": "Three requests per 300 seconds per canonical email.", "headers": { "Retry-After": { "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailVerificationRateLimitProblem" } } } }, "419": { "description": "Native CSRF middleware response for invalid stateful credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailVerificationMiddlewareError" } } } } } } }, "/api/registration-config": { "get": { "tags": [ "Authentication" ], "summary": "Public registration configuration", "operationId": "6b5c224479d8967d19da03c940a46ea3", "responses": { "200": { "description": "Only the public Turnstile sitekey.", "content": { "application/json": { "schema": { "required": [ "turnstileSiteKey" ], "properties": { "turnstileSiteKey": { "type": "string" } }, "type": "object" } } } }, "503": { "description": "Unusable human-verification configuration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailVerificationAvailabilityProblem" } } } } } } }, "/api/auth/reserved-admin-codes": { "get": { "tags": [ "Auth" ], "summary": "Return the BC-aggregated reserved admin role codes.", "description": "Read-only catalog of role codes reserved for tenant admins across every active bounded context (Backoffice today). Lets frontends derive the admin-codes list from the backend instead of hard-coding it (MER-641 / MER-785 follow-up).", "operationId": "getReservedAdminCodes", "responses": { "200": { "description": "Aggregated reserved admin role codes", "content": { "application/json": { "schema": { "required": [ "codes" ], "properties": { "codes": { "type": "array", "items": { "type": "string" }, "example": [ "SUPER_ADMIN" ] } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/auth/user/authorization": { "get": { "tags": [ "Auth - Users" ], "summary": "Get the authenticated user's authorization view for a company", "description": "Returns the unified authorization read model: explicit permissions, role codes, admin verdict, and the reason that justified it. Replaces ad-hoc derivation of the admin flag from a hard-coded role list on the frontend.", "operationId": "getUserAuthorization", "parameters": [ { "name": "company_id", "in": "query", "description": "Company ID to scope the authorization read to", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Authorization view retrieved successfully", "content": { "application/json": { "schema": { "properties": { "user_id": { "type": "integer" }, "company_id": { "type": "string" }, "permissions": { "type": "array", "items": { "type": "string" } }, "role_codes": { "type": "array", "items": { "type": "string" } }, "is_admin": { "type": "boolean" }, "admin_reason": { "type": "string", "enum": [ "ADMIN_BYPASS", "EXPLICIT_PERMISSION", "DENIED_NO_PERMISSION", "DENIED_TENANT_MISMATCH", "DENIED_NO_MEMBERSHIP" ] } }, "type": "object" } } } }, "400": { "description": "Bad Request - Missing company_id" }, "401": { "description": "Unauthorized" }, "404": { "description": "User has no membership in the requested company" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/auth/user": { "get": { "tags": [ "Auth - User" ], "summary": "Get specific users information", "operationId": "205c730b0e208eb365cd23e0cffbc5b3", "responses": { "200": { "description": "Successfully retrieved users information", "content": { "application/json": { "schema": { "properties": { "id": { "type": "string", "example": "f7c5bdb2-1f8e-4f19-9c6d-f8c4a4d54a9a" }, "name": { "type": "string", "example": "John Doe" }, "email": { "type": "string", "example": "john.doe@example.com" }, "defaultCompanyId": { "type": "string", "example": "comp-123" }, "companyName": { "type": "string", "example": "MedineTech" } }, "type": "object" } } } }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Resource not found" }, "status": { "type": "integer", "example": 404 }, "detail": { "type": "string", "example": "The requested users does not exist." } }, "type": "object" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Internal Server Error" }, "detail": { "type": "string", "example": "An unexpected error occurred" }, "status": { "type": "integer", "example": 500 } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/auth/user/permissions": { "get": { "tags": [ "Auth - Users" ], "summary": "Get current user's permissions for the current company", "operationId": "dd46eccc194997837148733637f3dd3b", "parameters": [ { "name": "company_id", "in": "query", "description": "Company ID to get permissions for", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "User permissions retrieved successfully", "content": { "application/json": { "schema": { "properties": { "permissions": { "type": "array", "items": { "type": "string" } } }, "type": "object" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Forbidden" }, "status": { "type": "integer", "example": 403 }, "detail": { "type": "string", "example": "Access denied" } }, "type": "object" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Bad Request" }, "status": { "type": "integer", "example": 400 }, "detail": { "type": "string", "example": "Company ID is required" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/auth/user/roles": { "get": { "tags": [ "Auth" ], "summary": "Get current user roles for a specific company", "description": "Returns the roles assigned to the authenticated user in the specified company context", "operationId": "getUserRoles", "parameters": [ { "name": "company_id", "in": "query", "description": "Company ID to get roles for", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "User roles retrieved successfully", "content": { "application/json": { "schema": { "properties": { "roles": { "type": "array", "items": { "type": "string" }, "example": [ "Super-Admin", "Manager" ] } }, "type": "object" } } } }, "400": { "description": "Bad Request - Missing company_id parameter", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Bad Request" }, "detail": { "type": "string", "example": "Company ID is required" }, "status": { "type": "integer", "example": 400 } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unauthorized" }, "detail": { "type": "string", "example": "Authentication required" }, "status": { "type": "integer", "example": 401 } }, "type": "object" } } } }, "403": { "description": "Forbidden - User doesn't belong to the specified company", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Forbidden" }, "detail": { "type": "string", "example": "Access denied to this company" }, "status": { "type": "integer", "example": 403 } }, "type": "object" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Internal Server Error" }, "detail": { "type": "string", "example": "An unexpected error occurred" }, "status": { "type": "integer", "example": 500 } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/verify-email/{id}/{hash}": { "get": { "tags": [ "Authentication" ], "summary": "Verify user email address", "operationId": "2a87bcc29fb717d6dd51a631c1b13064", "parameters": [ { "name": "id", "in": "path", "description": "User ID", "required": true, "schema": { "type": "integer" } }, { "name": "hash", "in": "path", "description": "Email verification hash", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Email verified successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "verified" }, "message": { "type": "string", "example": "Email verified successfully" } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unauthorized" }, "status": { "type": "integer", "example": 401 }, "detail": { "type": "string", "example": "Unauthenticated" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/verify-email-frontend": { "get": { "tags": [ "Authentication" ], "summary": "Verify user email address from frontend link", "operationId": "376b1d160a0c3dd6d7a0563ed99636c2", "parameters": [ { "name": "id", "in": "query", "description": "User ID", "required": true, "schema": { "type": "string" } }, { "name": "hash", "in": "query", "description": "Email verification hash", "required": true, "schema": { "type": "string" } }, { "name": "expires", "in": "query", "description": "Expiration timestamp", "required": true, "schema": { "type": "string" } }, { "name": "signature", "in": "query", "description": "Security signature", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Email verified successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "verified" }, "message": { "type": "string", "example": "Email verified successfully" } }, "type": "object" } } } }, "400": { "description": "Invalid or expired verification link (bodies differ by title/detail)", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Invalid Link" }, "status": { "type": "integer", "example": 400 }, "detail": { "type": "string", "example": "The verification link is invalid or has expired" } }, "type": "object" } } } } } } }, "/api/backoffice/{tenant}/accounting/accounting-accounts/lookup": { "get": { "tags": [ "Backoffice - Accounting - Accounting Account Lookups" ], "summary": "Lookup Accounting Accounts for tenant forms", "operationId": "74b6941d78b0d8daac1f7d3f4da17f72", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "active", "inactive" ] } }, { "name": "transactional_only", "in": "query", "description": "Legacy: `true` or `1` lists transactional accounts only (no direct subaccounts); `false` or `0` filters nothing.", "required": false, "schema": { "type": "string", "enum": [ "true", "false", "1", "0" ] } }, { "name": "id", "in": "query", "description": "When a valid UUID is sent, returns that company row only and ignores `status` and `transactional_only`. A blank value is ignored. A missing or foreign id yields an empty page.", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 200, "minimum": 1 } } ], "responses": { "200": { "description": "Minimal Accounting Account projection", "content": { "application/json": { "schema": { "properties": { "items": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "integer", "enum": [ 1, 2, 3, 4, 5, 6 ] }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "is_group": { "description": "True when the account has at least one child of the same company (MER-3567).", "type": "boolean" } }, "type": "object" } }, "total": { "type": "integer" }, "per_page": { "type": "integer" }, "current_page": { "type": "integer" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Not a member of this tenant" }, "404": { "description": "Tenant not found" }, "422": { "description": "Invalid status or transactional_only filter" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/accounting/accounting-accounts/{id}": { "get": { "tags": [ "Backoffice - Accounting - Accounting Accounts" ], "summary": "Get an accounting account by ID", "description": "Returns one of the company's accounting accounts: the list row's fields plus `children_count`, the direct subaccounts the company owns under it, and its `created_at` and `updated_at` as UTC instants. `has_children` is `children_count` above zero. Requires any of five view permissions (docs/backend/multi-permission-endpoint-carve-outs.md).", "operationId": "1f3db0e079de3f562d396f126a78ca1f", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant ID", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "description": "The ID of the accounting account to retrieve", "required": true, "schema": { "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426655440000" } } ], "responses": { "200": { "description": "The accounting account with its parent, subaccount count and timestamps", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountingAccountRecord" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user holds none of the five view permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountingAccountProblem" } } } }, "404": { "description": "Unknown id, or an account of another company; `error_code` is accounting_account_not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountingAccountProblem" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Internal Server Error" }, "status": { "type": "integer", "example": 500 }, "detail": { "type": "string", "example": "An unexpected error occurred." } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Backoffice - Accounting - Accounting Accounts" ], "summary": "Update an existing accounting account", "description": "Updates the name, description, type, status, parent and expense subtype; the code is immutable. Requires `backoffice.accounting.accounting-accounts.updated`.", "operationId": "cee96334d99bf309383ca19f699a42f6", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant ID", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "description": "The ID of the accounting account to update", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "type", "status" ], "properties": { "name": { "type": "string", "example": "Updated Account Name", "maxLength": 80, "minLength": 3 }, "description": { "type": "string", "example": "Updated account description", "nullable": true, "maxLength": 100, "minLength": 3 }, "type": { "description": "1 = asset, 2 = liability, 3 = equity, 4 = revenue, 5 = cost, 6 = expense", "type": "integer", "example": 1, "maximum": 6, "minimum": 1 }, "status": { "type": "string", "example": "inactive", "enum": [ "active", "inactive" ] }, "parent_id": { "description": "Parent account ID", "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426655440000", "nullable": true }, "expense_subtype": { "description": "Must be null when type is non-EXPENSE; otherwise 'operating' or 'tax'", "type": "string", "example": "operating", "nullable": true, "enum": [ "operating", "tax" ] } }, "type": "object" } } } }, "responses": { "200": { "description": "Accounting account updated successfully" }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks the update permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountingAccountProblem" } } } }, "404": { "description": "Unknown id, or an account of another company; `error_code` is accounting_account_not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountingAccountProblem" } } } }, "422": { "description": "Invalid fields (`error_code` null, `errors` keyed by field), or a domain refusal placed on its field: `accounting_hierarchy_cycle` on `parent_id`, `invalid_expense_subtype_for_account_type` on `expense_subtype`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountingAccountProblem" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Error" }, "status": { "type": "integer", "example": 500 }, "detail": { "type": "string", "example": "An unexpected error occurred while processing your request." } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/accounting/accounting-accounts/import": { "post": { "tags": [ "Backoffice - Accounting Accounts" ], "summary": "Import accounting accounts from Excel file", "description": "Imports accounting accounts with hierarchical structure from Excel file", "operationId": "6307a58eba6a07babc8957b73384ea5b", "parameters": [ { "name": "tenant", "in": "path", "description": "Company tenant ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "properties": { "file": { "description": "Excel file with accounting accounts", "type": "string", "format": "binary" } }, "type": "object" } } } }, "responses": { "202": { "description": "The import started in the background; poll its status with import_id.", "content": { "application/json": { "schema": { "required": [ "success", "import_id", "message" ], "properties": { "success": { "type": "boolean", "example": true }, "import_id": { "type": "string", "format": "uuid", "example": "0199a3c1-0000-7000-8000-0000000014a1" }, "message": { "type": "string", "example": "Importación iniciada correctamente." } }, "type": "object" } } } }, "400": { "description": "The workbook was refused before any write, at its first problem in row order. Each typed refusal answers its own error_code and data: an unreadable file, mismatched columns, more rows than one import takes, no data row, a row missing its code, name or type, a row whose type is not one of the six labels, a malformed code, a role the row type does not take, a role the file repeats, a role on an account with subaccounts in the file, or an expense subtype the row type does not take.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AccountingAccountImportFileUnreadableProblem" }, { "$ref": "#/components/schemas/AccountingAccountImportColumnsMismatchProblem" }, { "$ref": "#/components/schemas/AccountingAccountImportTooManyRowsProblem" }, { "$ref": "#/components/schemas/AccountingAccountImportFileEmptyProblem" }, { "$ref": "#/components/schemas/AccountingAccountImportRequiredCellMissingProblem" }, { "$ref": "#/components/schemas/AccountingAccountImportTypeNotRecognizedProblem" }, { "$ref": "#/components/schemas/AccountingAccountImportCodeMalformedProblem" }, { "$ref": "#/components/schemas/AccountingAccountImportRoleNotAllowedProblem" }, { "$ref": "#/components/schemas/AccountingAccountImportRoleRepeatedProblem" }, { "$ref": "#/components/schemas/AccountingAccountImportRoleRequiresLeafAccountProblem" }, { "$ref": "#/components/schemas/AccountingAccountImportExpenseSubtypeNotAllowedProblem" } ] } } } }, "403": { "description": "Unauthorized - User does not have permission to import accounts" }, "409": { "description": "accounting_account_code_already_exists: the file repeats codes (codes_repeated_in_file lists them) or brings codes the company already holds (codes_already_in_chart lists every one of them); exactly one list is non-empty.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountingAccountCodeAlreadyExistsProblem" } } } }, "422": { "description": "Validation error - Invalid file format or missing file" }, "500": { "description": "An undeclared failure, reported: any other error that would answer 400 is never one of the declared refusals above, so it answers 500 instead." }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/accounting/accounting-accounts/import/{importId}/status": { "get": { "tags": [ "Accounting Accounts" ], "summary": "Consultar estado de importación de cuentas contables", "description": "Obtiene el estado actual de una importación de cuentas contables", "operationId": "getAccountingAccountImportStatus", "parameters": [ { "name": "tenant", "in": "path", "description": "ID de la empresa", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "importId", "in": "path", "description": "ID de la importación", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Estado de la importación obtenido exitosamente", "content": { "application/json": { "schema": { "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed" ] }, "progress": { "type": "integer", "maximum": 100, "minimum": 0 }, "imported_count": { "type": "integer" }, "total_count": { "type": "integer" }, "errors": { "type": "array", "items": { "type": "string" } }, "assigned_roles": { "description": "Roles assigned by this import; existing assignments are preserved", "type": "array", "items": { "type": "string" } }, "original_filename": { "type": "string" }, "started_at": { "type": "string", "format": "date-time", "nullable": true }, "completed_at": { "type": "string", "format": "date-time", "nullable": true } }, "type": "object" } } } }, "404": { "description": "Import job not found or belongs to another company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountingAccountProblem" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unauthorized" }, "status": { "type": "integer", "example": 403 }, "detail": { "type": "string", "example": "You do not have permission to view this resource." } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/accounting/accounting-accounts": { "get": { "tags": [ "Backoffice - Accounting - Accounting Accounts" ], "summary": "Search the company's chart of accounts", "description": "Lists the company's accounting accounts with each one's group flag and parent. `status` and `type` take one value or several (`status=inactive` or `status[]=active&status[]=inactive`): values of one filter are alternatives, filters narrow each other, and `status=all` or an empty filter is ignored. `search` matches the name, the code or the description literally; it is trimmed and a blank term searches nothing. Without `sort_by` the order is code ascending; a `sort_by` sent without `sort_order` reads descending, and a `sort_order` sent alone applies to the code. Ties are settled by id, ascending. `group_by=type` orders by type and `group_by=status` lists active accounts before inactive ones, both ahead of the requested order and before paging. `meta.counts` counts the matching accounts by status under every filter but `status`, and `meta.type_counts` by type under every filter but `type`; both are zero-filled and do not depend on the page, its size, the order or the grouping. Unknown parameters are ignored. Requires any of seven view permissions (docs/backend/multi-permission-endpoint-carve-outs.md).", "operationId": "50b5c7109b85e1930afa54a0b7651a53", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant ID", "required": true, "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "One status, or `all` for every status. Same as one `status[]`.", "required": false, "schema": { "type": "string", "enum": [ "active", "inactive", "all" ] } }, { "name": "status[]", "in": "query", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "active", "inactive" ] } } }, { "name": "type", "in": "query", "description": "One account type: 1 = asset, 2 = liability, 3 = equity, 4 = revenue, 5 = cost, 6 = expense. Same as one `type[]`.", "required": false, "schema": { "type": "integer", "maximum": 6, "minimum": 1 } }, { "name": "type[]", "in": "query", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "integer", "maximum": 6, "minimum": 1 } } }, { "name": "parent_id", "in": "query", "description": "Lists the direct children of this account only.", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "has_children", "in": "query", "description": "`true` lists group accounts, which own a direct subaccount; `false` lists transactional ones.", "required": false, "schema": { "type": "string", "enum": [ "true", "false", "1", "0" ] } }, { "name": "transactional_only", "in": "query", "description": "Legacy: `true` is `has_children=false`; `false` filters nothing.", "required": false, "schema": { "type": "string", "enum": [ "true", "false", "1", "0" ] } }, { "name": "search", "in": "query", "description": "Matches the name, the code or the description, literally; trimmed, and blank searches nothing.", "required": false, "schema": { "type": "string", "maxLength": 255 } }, { "name": "name", "in": "query", "description": "Legacy partial filter on the name, matched literally.", "required": false, "schema": { "type": "string", "maxLength": 255 } }, { "name": "code", "in": "query", "description": "Legacy partial filter on the code, matched literally.", "required": false, "schema": { "type": "string", "maxLength": 255 } }, { "name": "description", "in": "query", "description": "Legacy partial filter on the description, matched literally.", "required": false, "schema": { "type": "string", "maxLength": 255 } }, { "name": "exclude_subtree_of", "in": "query", "description": "Hides the given accounting account and every descendant of it, at any depth, from the results. The parent picker sends the account being edited so the options it offers cannot form an accounting hierarchy cycle. Descendants are resolved by walking parent_id, never by matching the accounting-code prefix. Opt-in: omit it and results are unchanged.", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "sort_by", "in": "query", "required": false, "schema": { "type": "string", "default": "code", "enum": [ "code", "name" ] } }, { "name": "sort_order", "in": "query", "description": "Ascending when `sort_by` is omitted; descending when `sort_by` is sent without it. Trimmed, any case.", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "group_by", "in": "query", "description": "`type` orders by type, `status` lists active accounts first; both before the requested order and before paging. `none` groups nothing.", "required": false, "schema": { "type": "string", "enum": [ "type", "status", "none" ] } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "A page of accounting accounts with the list's status and type counts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountingAccountsPage" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user holds none of the seven view permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountingAccountProblem" } } } }, "422": { "description": "Invalid filter, search, sort, grouping or pagination parameter; `errors` names it, `status.0` for the first status of a list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountingAccountProblem" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Internal Server Error" }, "detail": { "type": "string", "example": "An unexpected error occurred" }, "status": { "type": "integer", "example": 500 } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Accounting - Accounting Accounts" ], "summary": "Create a new accounting account", "description": "Creates an active accounting account under the client-generated id. An id already in use answers 409 and changes nothing. Requires `backoffice.accounting.accounting-accounts.created`.", "operationId": "8fa28129042baf3e6f59635291d4d927", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "id", "name", "code", "type" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426655440000" }, "name": { "type": "string", "example": "Cash Account", "maxLength": 80, "minLength": 3 }, "description": { "type": "string", "example": "Cash account for the company", "nullable": true, "maxLength": 100, "minLength": 3 }, "code": { "type": "string", "example": "1.1.01.", "maxLength": 80, "minLength": 3 }, "type": { "description": "1 = asset, 2 = liability, 3 = equity, 4 = revenue, 5 = cost, 6 = expense", "type": "integer", "example": 1, "maximum": 6, "minimum": 1 }, "parent_id": { "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426655440001", "nullable": true }, "expense_subtype": { "description": "Required to be null for non-EXPENSE accounts; otherwise 'operating' or 'tax'", "type": "string", "example": "operating", "nullable": true, "enum": [ "operating", "tax" ] }, "status": { "description": "When present must be active or inactive. Create always persists the account as active; this field is not applied on create.", "type": "string", "enum": [ "active", "inactive" ] } }, "type": "object" } } } }, "responses": { "201": { "description": "Accounting account created successfully" }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks the create permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountingAccountProblem" } } } }, "409": { "description": "The id is already in use; nothing is written. `error_code` is accounting_account_already_exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountingAccountProblem" } } } }, "422": { "description": "Invalid fields (`error_code` null, `errors` keyed by field), or a domain refusal placed on its field: `accounting_hierarchy_cycle` on `parent_id`, `invalid_expense_subtype_for_account_type` on `expense_subtype`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountingAccountProblem" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Internal Server Error" }, "status": { "type": "integer", "example": 500 }, "detail": { "type": "string", "example": "An unexpected error occurred while processing your request." } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/accounting/accounting-accounts/template-accounting": { "get": { "tags": [ "Backoffice - Accounting Accounts" ], "summary": "Download accounting accounts import template", "description": "Downloads an Excel template file for importing accounting accounts. Its rows are the chart of accounts of the current Venezuela Company Template (VE), the version company provisioning applies, with the optional Rol contable and Subtipo gasto columns. Account types: 1=Activo, 2=Pasivo, 3=Patrimonio, 4=Ingreso, 5=Costo, 6=Gasto", "operationId": "091870974364163855884a9c6632d9fa", "parameters": [ { "name": "tenant", "in": "path", "description": "Company tenant ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Excel template file downloaded successfully", "headers": { "Cache-Control": { "description": "Always no-store: the workbook is never cached", "schema": { "type": "string", "example": "no-store, private" } } }, "content": { "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": {} } }, "403": { "description": "Problem JSON, title Forbidden. Without backoffice.accounting.accounting-accounts.view the route can: middleware answers with error_code and errors null; the tenant middleware stack (API-key guardrails, company access, tenant membership) answers without error_code, with a reason only from tenant membership.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ImportTemplateProblem" }, { "$ref": "#/components/schemas/ImportTemplateMiddlewareForbidden" } ] } } } }, "500": { "description": "Unexpected failure, reported. Problem JSON with error_code and errors null; the detail is generic in production.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportTemplateProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/accounting/accounting-centers/lookup": { "get": { "tags": [ "Backoffice - Accounting - Accounting Center Lookups" ], "summary": "Lookup Accounting Centers for tenant forms", "operationId": "d10858511a7f376d59ce852f732ba786", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "active", "inactive" ] } }, { "name": "id", "in": "query", "description": "When a valid UUID is sent, returns that company row only and ignores `status`. A blank value is ignored. A missing or foreign id yields an empty page.", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 200, "minimum": 1 } } ], "responses": { "200": { "description": "Minimal Accounting Center projection", "content": { "application/json": { "schema": { "properties": { "items": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "inactive" ] } }, "type": "object" } }, "total": { "type": "integer" }, "per_page": { "type": "integer" }, "current_page": { "type": "integer" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Not a member of this tenant" }, "404": { "description": "Tenant not found" }, "422": { "description": "Invalid status filter" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/accounting/accounting-centers/{id}": { "get": { "tags": [ "Backoffice - Accounting - Accounting Centers" ], "summary": "Retrieve an accounting center by ID", "description": "Returns one of the company's accounting centers with the list row's shape: its Responsable name while that user is a member of the company, its parent's code and name, and its `createdAt` and `updatedAt` as UTC instants. Requires `backoffice.accounting.accounting-centers.view`.", "operationId": "7e59caac36647f09a9cfb1fe04be0619", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "Accounting Center ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The accounting center with its Responsable name, parent and timestamps", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountingCenter" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks the view permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountingCenterProblem" } } } }, "404": { "description": "Unknown id, or a center of another company; `error_code` is accounting_center_not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountingCenterProblem" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Internal Server Error" }, "status": { "type": "integer", "example": 500 }, "detail": { "type": "string", "example": "An Unexpected Error Occurred" } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Backoffice - Accounting - Accounting Centers" ], "summary": "Update an existing accounting center", "description": "Updates the name, description, status, parent and, when sent, the Responsable of one of the company's accounting centers; the code never changes. `status` must be `active` or `inactive`. Omitting `responsible_user_id` keeps the stored Responsable (ADR 0102). Requires `backoffice.accounting.accounting-centers.update`.", "operationId": "637f3147b0942fee681350bac51b3e4a", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "The ID of the accounting center to update", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "status" ], "properties": { "name": { "type": "string", "example": "Updated Center Name", "maxLength": 80, "minLength": 3 }, "description": { "type": "string", "example": "Updated accounting center description", "nullable": true }, "status": { "description": "Center status", "type": "string", "example": "inactive", "enum": [ "active", "inactive" ] }, "parent_id": { "description": "Parent center ID", "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426655440000", "nullable": true }, "responsible_user_id": { "description": "Same-company responsible user ID; omit it to keep the stored one", "type": "integer", "example": 41, "minimum": 1 } }, "type": "object" } } } }, "responses": { "200": { "description": "Accounting center updated successfully" }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks the update permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountingCenterProblem" } } } }, "404": { "description": "Unknown id, or a center of another company; `error_code` is accounting_center_not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountingCenterProblem" } } } }, "422": { "description": "Invalid fields (`error_code` null, `errors` keyed by field), or a domain refusal placed on its field: `accounting_center_hierarchy_cycle` or `accounting_center_parent_not_found` on `parent_id`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountingCenterProblem" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Error" }, "status": { "type": "integer", "example": 500 }, "detail": { "type": "string", "example": "An unexpected error occurred while processing your request." } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/accounting/accounting-centers": { "get": { "tags": [ "Backoffice - Accounting - Accounting Centers" ], "summary": "Search the company's accounting centers", "description": "Lists the company's accounting centers with each one's Responsable name, parent and timestamps. `status` takes one value or several (`status=active` or `status[]=active&status[]=inactive`): the values are alternatives, and `status=all` or an empty status is ignored. `responsible_user_id` takes one or more Responsable user ids, comma-joined (`41,73`) or bracketed (`responsible_user_id[]=41`); a blank value is ignored. `parent_id` lists the direct children of one center. `search` matches the name, the code or the description literally; it is trimmed and a blank term searches nothing. Without `sort_by` the order is code ascending; a `sort_by` sent without `sort_order` reads descending, and a `sort_order` sent alone applies to the code. Ties are settled by id, ascending. `group_by=status` lists active centers before inactive ones, ahead of the requested order and before paging. `meta.counts` counts the matching centers by status under every filter but `status`, zero-filled and independent of the page, its size, the order and the grouping. Unknown parameters are ignored. Requires backoffice.accounting.accounting-centers.view on the route; cross-module catalogs use /accounting-centers/lookup.", "operationId": "4d23008111f292059007264f77558a10", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "description": "One status, or `all` for every status. Same as one `status[]`.", "required": false, "schema": { "type": "string", "enum": [ "active", "inactive", "all" ] } }, { "name": "status[]", "in": "query", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "active", "inactive" ] } } }, { "name": "responsible_user_id", "in": "query", "description": "One or more Responsable user ids, comma-joined (`41,73`). Centers assigned to any listed user are returned. A blank value applies no filter.", "required": false, "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "integer", "minimum": 1 } } }, { "name": "responsible_user_id[]", "in": "query", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "integer", "minimum": 1 } } }, { "name": "parent_id", "in": "query", "description": "Lists the direct children of this center only.", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "search", "in": "query", "description": "Matches the name, the code or the description, literally; trimmed, and blank searches nothing. Never matches the Responsable name.", "required": false, "schema": { "type": "string", "maxLength": 255 } }, { "name": "name", "in": "query", "description": "Legacy partial filter on the name, matched literally.", "required": false, "schema": { "type": "string", "maxLength": 255 } }, { "name": "code", "in": "query", "description": "Legacy partial filter on the code, matched literally.", "required": false, "schema": { "type": "string", "maxLength": 255 } }, { "name": "description", "in": "query", "description": "Legacy partial filter on the description, matched literally.", "required": false, "schema": { "type": "string", "maxLength": 255 } }, { "name": "sort_by", "in": "query", "required": false, "schema": { "type": "string", "default": "code", "enum": [ "code", "name" ] } }, { "name": "sort_order", "in": "query", "description": "Ascending when `sort_by` is omitted; descending when `sort_by` is sent without it. Trimmed, any case.", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "group_by", "in": "query", "description": "`status` lists active centers first, before the requested order and before paging. `none` groups nothing.", "required": false, "schema": { "type": "string", "enum": [ "status", "none" ] } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "A page of accounting centers with the list's status counts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountingCentersPage" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks the accounting centers view permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountingCenterProblem" } } } }, "422": { "description": "Invalid filter, search, sort, grouping or pagination parameter; `errors` names it, `status.0` for the first status of a list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountingCenterProblem" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Internal Server Error" }, "detail": { "type": "string", "example": "An unexpected error occurred" }, "status": { "type": "integer", "example": 500 } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Accounting - Accounting Centers" ], "summary": "Create a new accounting center", "description": "Creates an active accounting center under the client-generated id, with a Responsable who is a member of the company. An id already in use, by this company or another one, answers 409 and changes nothing. Requires `backoffice.accounting.accounting-centers.create`.", "operationId": "509908f36d7f5fb589c8c45dfc2a09b6", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "id", "code", "name", "responsible_user_id" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426655440000" }, "code": { "type": "string", "example": "AC-001", "maxLength": 50 }, "name": { "type": "string", "example": "Main Accounting Center", "maxLength": 80, "minLength": 3 }, "description": { "type": "string", "example": "Main accounting center description", "nullable": true }, "parent_id": { "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426655440001", "nullable": true }, "responsible_user_id": { "description": "A member of the company", "type": "integer", "example": 41, "minimum": 1 } }, "type": "object" } } } }, "responses": { "201": { "description": "Accounting center created successfully" }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks the create permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountingCenterProblem" } } } }, "409": { "description": "The id is already in use; nothing is written. `error_code` is accounting_center_already_exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountingCenterProblem" } } } }, "422": { "description": "Invalid fields (`error_code` null, `errors` keyed by field), or a domain refusal placed on its field: `accounting_center_hierarchy_cycle` or `accounting_center_parent_not_found` on `parent_id`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountingCenterProblem" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Internal Server Error" }, "status": { "type": "integer", "example": 500 }, "detail": { "type": "string", "example": "An unexpected error occurred while processing your request." } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/accounting/accounting-periods/{period}/close": { "post": { "tags": [ "Backoffice - Accounting - Accounting Periods" ], "summary": "Close an accounting period", "description": "Closes one calendar month of the company's ledger (ADR 0235). Only a month that has ended in the company's timezone closes, so the current month is always open. The first close may name any ended month and closes every earlier month with it; after that only the month right after the closed-through month can close. Once a month is closed, every ledger entry dated in it or earlier is refused with 422 `accounting_configuration_incomplete` and the reason `ACCOUNTING_PERIOD_CLOSED`, details `[month, date]`; a reversal dated in it is posted on the company's today instead (ADR 0236). Requires `backoffice.accounting.accounting-periods.close`.", "operationId": "closeAccountingPeriod", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "period", "in": "path", "description": "The month to close, YYYY-MM", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$", "example": "2026-08" } } ], "responses": { "200": { "description": "The month is closed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountingPeriod" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks the close permission" }, "404": { "description": "The company does not exist (company_not_found)", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "detail": { "type": "string" }, "error_code": { "type": "string", "example": "company_not_found" } }, "type": "object" } } } }, "409": { "description": "The month is on or before the closed-through month (accounting_period_already_closed)", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "detail": { "type": "string", "example": "El período contable <2026-08> ya está cerrado; los meses de la empresa están cerrados hasta <2026-08>" }, "error_code": { "type": "string", "example": "accounting_period_already_closed" } }, "type": "object" } } } }, "422": { "description": "The period is not a YYYY-MM month (errors.period), the month has not ended in the company's timezone (accounting_period_not_ended), or it is not the month right after the closed-through month, which the detail names (accounting_period_out_of_order)", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string", "example": "El período contable <2026-10> no se puede cerrar antes que <2026-09>; cierra <2026-09> primero" }, "error_code": { "type": "string", "example": "accounting_period_out_of_order", "nullable": true }, "errors": { "type": "object", "nullable": true } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/accounting/accounting-periods/{period}/reopen": { "post": { "tags": [ "Backoffice - Accounting - Accounting Periods" ], "summary": "Reopen the closed-through accounting period", "description": "Reopens the company's closed-through month, the latest closed one (ADR 0235), so entries dated in it post again; the month before it becomes the closed-through month, or no month stays closed when it was the only one. Only the closed-through month reopens, so the closed months stay one run. The month keeps who closed it, records who reopened it, when and why, and the reopening is audited as `backoffice.accounting.accounting-periods.reopened`. Requires `backoffice.accounting.accounting-periods.reopen`; the close permission alone is not enough.", "operationId": "reopenAccountingPeriod", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "period", "in": "path", "description": "The month to reopen, YYYY-MM", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$", "example": "2026-09" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "reason" ], "properties": { "reason": { "description": "Why the month reopens. Surrounding whitespace is trimmed first and the 1 to 500 characters are counted on what remains; inner line breaks are kept and a blank reason is refused.", "type": "string", "example": "Factura de proveedor recibida tarde", "maxLength": 500, "minLength": 1 } }, "type": "object" } } } }, "responses": { "200": { "description": "The month is open again", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountingPeriod" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks the reopen permission" }, "404": { "description": "The company does not exist (company_not_found)", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "detail": { "type": "string" }, "error_code": { "type": "string", "example": "company_not_found" } }, "type": "object" } } } }, "409": { "description": "The month is open, so there is nothing to reopen (accounting_period_not_closed)", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "detail": { "type": "string", "example": "El período contable <2026-10> está abierto; solo se puede reabrir un mes cerrado" }, "error_code": { "type": "string", "example": "accounting_period_not_closed" } }, "type": "object" } } } }, "422": { "description": "The period is not a YYYY-MM month (errors.period), the reason is blank or longer than 500 characters once trimmed (errors.reason), or the month is closed but is not the closed-through month, which the detail names (accounting_period_not_latest_closed)", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string", "example": "El período contable <2026-08> no se puede reabrir antes que <2026-09>; reabre <2026-09> primero" }, "error_code": { "type": "string", "example": "accounting_period_not_latest_closed", "nullable": true }, "errors": { "type": "object", "nullable": true } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/accounting/accounting-periods": { "get": { "tags": [ "Backoffice - Accounting - Accounting Periods" ], "summary": "List the accounting periods", "description": "Lists the company's current month, in its timezone, and the eleven months before it, plus every older month that was ever closed or reopened, newest first, so the first item is always the current month. A month on or before `closed_through`, the latest closed month, is closed; when no month is closed, `closed_through` is null and every month is open (ADR 0235). Requires `backoffice.accounting.accounting-periods.view`.", "operationId": "searchAccountingPeriods", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The company's accounting periods", "content": { "application/json": { "schema": { "required": [ "closed_through", "periods" ], "properties": { "closed_through": { "description": "The latest closed month, YYYY-MM; null when no month is closed.", "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$", "example": "2026-08", "nullable": true }, "periods": { "description": "Newest first; the first item is the current month.", "type": "array", "items": { "$ref": "#/components/schemas/AccountingPeriod" } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks the view permission" }, "404": { "description": "The company does not exist (company_not_found)", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "detail": { "type": "string" }, "error_code": { "type": "string", "example": "company_not_found" } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/accounting/pnl-dashboard/snapshot": { "get": { "tags": [ "Accounting / P&L Dashboard" ], "summary": "Fetch P&L snapshot for a given period", "operationId": "2b0c983c8e51630a512d24f8677fb7b0", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "period", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "today", "last_30_days", "mtd", "ytd" ] } }, { "name": "currency", "in": "query", "description": "Ledger book to sum. Defaults to reporting when omitted.", "required": false, "schema": { "type": "string", "default": "reporting", "enum": [ "functional", "reporting" ] } } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks backoffice.accounting.pnl-dashboard.view" }, "404": { "description": "Tenant mismatch / route not found" }, "422": { "description": "Unknown period, currency, or rejected as_of" }, "503": { "description": "Upstream ledger query failed" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/accounting/exchange-rates/{id}/affected-snapshots": { "get": { "tags": [ "Backoffice - Accounting - Exchange Rates" ], "summary": "List Rate Snapshots that referenced a losing rate version", "description": "Informative list of the records that took the given rate version, one per book it valued: ledger lines (ledger_line), purchases invoices (purchases_invoice), purchases debit notes (purchases_debit_note), purchases payments (purchases_payment), sales collections (sales_collection), sales invoices (sales_invoice) and sales debit notes (sales_debit_note). Snapshots are never re-valued (ADR 0124).", "operationId": "2b20644f8873c20172cc4ee08e19ec7d", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "Losing rate version id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Affected snapshots (possibly empty)", "content": { "application/json": { "schema": { "properties": { "items": { "type": "array", "items": { "required": [ "source", "transaction_item_id", "transaction_id", "reference_field", "date", "document_code" ], "properties": { "source": { "type": "string", "example": "ledger_line" }, "transaction_item_id": { "type": "string", "format": "uuid" }, "transaction_id": { "type": "string", "format": "uuid" }, "reference_field": { "type": "string", "enum": [ "functional_rate_reference", "reporting_rate_reference", "bolivar_rate_reference" ] }, "date": { "type": "string", "format": "date" }, "document_code": { "description": "Code of the record transaction_id identifies: the document's own code for document and cash sources, the accounting entry's code for a ledger line. Null when that record has no code.", "type": "string", "example": "INV2600001", "nullable": true } }, "type": "object" } } }, "type": "object" } } } }, "403": { "description": "Missing backoffice.accounting.settings.exchange-rates.view" }, "422": { "description": "Malformed path id" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/accounting/exchange-rates/{id}/supersessions": { "post": { "tags": [ "Backoffice - Accounting - Exchange Rates" ], "summary": "Supersede a manual exchange rate with a corrected version", "description": "Rate Supersession (ADR 0124): creates a new Manual Official Rate or Management Reference version with supersedes_id pointing at the replaced id. Pair, type and effective_date are conserved. A global ingested Official BCV Rate answers 422; a version already superseded answers 409.", "operationId": "c56d1f258ab7d6e6bbcc33dd0003d336", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "The rate version being replaced", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "id", "rate", "source", "reason" ], "properties": { "id": { "description": "Client-supplied id of the NEW replacement version", "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426655440001" }, "rate": { "type": "string", "pattern": "^\\d+\\.\\d{1,8}$", "example": "490.00000000" }, "source": { "type": "string", "example": "https://bcv.org.ve/corrected", "maxLength": 255 }, "reason": { "type": "string", "example": "Typo in the original quote", "maxLength": 1000 } }, "type": "object" } } } }, "responses": { "201": { "description": "Replacement version recorded", "content": { "application/json": { "schema": { "properties": { "id": { "type": "string", "format": "uuid" }, "supersedes_id": { "type": "string", "format": "uuid" }, "type": { "type": "string" }, "base_currency": { "type": "string" }, "quote_currency": { "type": "string" }, "rate": { "type": "string" }, "effective_date": { "type": "string", "format": "date", "nullable": true } }, "type": "object" } } } }, "403": { "description": "Missing backoffice.accounting.settings.exchange-rates.supersede" }, "404": { "description": "manual_official_rate_not_found or tenant does not exist" }, "409": { "description": "exchange_rate_already_superseded", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "error_code": { "type": "string", "example": "exchange_rate_already_superseded" } }, "type": "object" } } } }, "422": { "description": "Validation errors, exchange_rate_supersession_reason_required, or cannot_supersede_global_official_rate", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "error_code": { "type": "string", "nullable": true, "enum": [ "exchange_rate_supersession_reason_required", "cannot_supersede_global_official_rate" ] }, "errors": { "type": "object", "nullable": true } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/accounting/exchange-rates": { "get": { "tags": [ "Backoffice - Accounting - Exchange Rates" ], "summary": "Search the exchange-rate history", "description": "Paginated union of global Official BCV Rates and the company's Manual Official Rates / Management References. Superseded versions are included and linked via superseded_by_id.", "operationId": "108c4d5af5009944cecf2ec86a5d7977", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "official_bcv", "management_reference" ] } }, { "name": "base_currency", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "USD", "EUR", "USDT" ] } }, { "name": "quote_currency", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "VES" ] } }, { "name": "date_from", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "date_to", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 15, "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "History page", "content": { "application/json": { "schema": { "properties": { "items": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "origin": { "type": "string", "enum": [ "ingested", "manual" ] }, "type": { "type": "string", "enum": [ "official_bcv", "management_reference" ] }, "base_currency": { "type": "string" }, "quote_currency": { "type": "string" }, "rate": { "type": "string" }, "effective_date": { "type": "string", "format": "date", "nullable": true }, "side": { "type": "string", "nullable": true, "enum": [ "buy", "sell" ] }, "channel": { "type": "string", "nullable": true }, "observed_at": { "type": "string", "format": "date-time", "nullable": true }, "source": { "type": "string" }, "reason": { "type": "string", "nullable": true }, "captured_at": { "type": "string" }, "recorded_by_user_id": { "type": "string", "nullable": true }, "supersedes_id": { "type": "string", "format": "uuid", "nullable": true }, "superseded_by_id": { "type": "string", "format": "uuid", "nullable": true } }, "type": "object" } }, "total": { "type": "integer" }, "per_page": { "type": "integer" }, "current_page": { "type": "integer" } }, "type": "object" } } } }, "403": { "description": "Missing backoffice.accounting.settings.exchange-rates.view" }, "422": { "description": "Invalid filters — including when date_to is before date_from (after_or_equal:date_from)" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/accounting/exchange-rates/management-references/latest": { "get": { "tags": [ "Backoffice - Accounting - Exchange Rates" ], "summary": "The latest Management Reference of a pair and side observed by the end of a date", "description": "Management-only and informative (ADR 0124): the latest non-superseded Management Reference of the side asked for, observed before 00:00 of the day after `date` in the company's timezone. A reference of the other side never answers (no fallback, MER-3205). Absence is reference=null, never an error. Never values a document.", "operationId": "23ce4d384924d0d7d4b31f04b7c64f80", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "base_currency", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "USD", "USDT" ] } }, { "name": "quote_currency", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "VES" ] } }, { "name": "side", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "buy", "sell" ] } }, { "name": "date", "in": "query", "description": "Calendar day in the company's timezone", "required": true, "schema": { "type": "string", "format": "date", "example": "2026-10-01" } } ], "responses": { "200": { "description": "The latest reference of that side, or null when none was observed by the end of the date", "content": { "application/json": { "schema": { "required": [ "reference" ], "properties": { "reference": { "required": [ "id", "base_currency", "quote_currency", "side", "channel", "source", "observed_at", "rate" ], "properties": { "id": { "type": "string", "format": "uuid" }, "base_currency": { "type": "string", "enum": [ "USD", "USDT" ] }, "quote_currency": { "type": "string", "enum": [ "VES" ] }, "side": { "type": "string", "enum": [ "buy", "sell" ] }, "channel": { "type": "string", "example": "Binance P2P" }, "source": { "type": "string", "example": "manual desk capture" }, "observed_at": { "type": "string", "format": "date-time", "example": "2026-10-02T03:59:59+00:00" }, "rate": { "description": "VES per unit of base, scale-8 decimal string", "type": "string", "pattern": "^\\d+\\.\\d{8}$", "example": "146.00000000" } }, "type": "object", "nullable": true, "additionalProperties": false } }, "type": "object", "additionalProperties": false } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Missing backoffice.accounting.settings.exchange-rates.view, or not a member of this tenant" }, "404": { "description": "Tenant does not exist, or a company-bound API key of another company" }, "422": { "description": "Missing or invalid base_currency, quote_currency, side or date" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/accounting/exchange-rates/management-references": { "post": { "tags": [ "Backoffice - Accounting - Exchange Rates" ], "summary": "Record a Management Reference tip", "description": "Company-scoped management-only market tip (ADR 0124, glossary Management Reference). Never values a fiscal document or ledger entry. Forbidden wire name: internal_reference. Pairs are USD/VES or USDT/VES only — never EUR or Official BCV.", "operationId": "4f22741271ed6643ae5ec5fe4245bfe6", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "id", "base_currency", "quote_currency", "side", "channel", "source", "observed_at", "rate" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426655440000" }, "base_currency": { "type": "string", "example": "USDT", "enum": [ "USD", "USDT" ] }, "quote_currency": { "type": "string", "example": "VES", "enum": [ "VES" ] }, "side": { "type": "string", "example": "buy", "enum": [ "buy", "sell" ] }, "channel": { "type": "string", "pattern": ".*\\S.*", "example": "Binance P2P · Pago Móvil", "maxLength": 64, "minLength": 1 }, "source": { "type": "string", "pattern": ".*\\S.*", "example": "manual desk capture", "maxLength": 255, "minLength": 1 }, "observed_at": { "type": "string", "format": "date-time", "example": "2026-04-20T14:30:00Z" }, "rate": { "type": "string", "pattern": "^\\d+\\.\\d{1,8}$", "example": "485.50000000" } }, "type": "object" } } } }, "responses": { "201": { "description": "Management Reference recorded", "content": { "application/json": { "schema": { "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "example": "management_reference" }, "base_currency": { "type": "string" }, "quote_currency": { "type": "string" }, "side": { "type": "string" }, "channel": { "type": "string" }, "source": { "type": "string" }, "observed_at": { "type": "string" }, "rate": { "type": "string" } }, "type": "object" } } } }, "403": { "description": "Missing backoffice.accounting.settings.exchange-rates.create" }, "404": { "description": "Tenant does not exist (indistinguishable from missing route)" }, "409": { "description": "management_reference_already_recorded: a retried POST reused a client id that is already stored", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "error_code": { "type": "string", "example": "management_reference_already_recorded" } }, "type": "object" } } } }, "422": { "description": "Either an `errors` map keyed by field (shape validation) or a domain `error_code`", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "error_code": { "type": "string", "nullable": true, "enum": [ "management_reference_side_required", "management_reference_channel_required", "management_reference_observed_at_required", "management_reference_base_currency_not_allowed", "management_reference_quote_must_be_ves" ] }, "errors": { "type": "object", "nullable": true } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/accounting/exchange-rates/official": { "post": { "tags": [ "Backoffice - Accounting - Exchange Rates" ], "summary": "Record a manual official rate", "description": "Company-scoped gap-fill for the public official BCV rate (ADR 0145, ADR 0124). `effective_date` is required. The value date cannot be more than 5 days ahead of Caracas today, and cannot be a date the official BCV ingestion already covers. Management Reference tips use POST .../management-references (MER-2807).", "operationId": "ae080e6d0c2577152a4d5baada670300", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "id", "type", "base_currency", "quote_currency", "rate", "source", "reason" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426655440000" }, "type": { "type": "string", "example": "official_bcv", "enum": [ "official_bcv" ] }, "base_currency": { "type": "string", "example": "USD", "enum": [ "USD", "EUR" ] }, "quote_currency": { "type": "string", "example": "VES", "enum": [ "VES" ] }, "rate": { "type": "string", "pattern": "^\\d+\\.\\d{1,8}$", "example": "481.21770000" }, "effective_date": { "description": "Required for official_bcv", "type": "string", "format": "date", "example": "2026-04-20", "nullable": true }, "source": { "type": "string", "example": "https://bcv.org.ve", "maxLength": 255 }, "reason": { "type": "string", "example": "BCV site unreachable; gap-filled from a bank quote", "maxLength": 1000 } }, "type": "object" } } } }, "responses": { "201": { "description": "Manual official rate recorded", "content": { "application/json": { "schema": { "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string" }, "base_currency": { "type": "string" }, "quote_currency": { "type": "string" }, "rate": { "type": "string" }, "effective_date": { "type": "string", "format": "date", "nullable": true } }, "type": "object" } } } }, "403": { "description": "Missing backoffice.accounting.settings.exchange-rates.create" }, "404": { "description": "Tenant does not exist (indistinguishable from missing route)" }, "409": { "description": "manual_official_rate_value_date_already_covered: the official BCV ingestion already has this pair/date, or manual_official_rate_already_recorded: a race on the same company/pair/date", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "error_code": { "type": "string", "example": "manual_official_rate_value_date_already_covered" } }, "type": "object" } } } }, "422": { "description": "Either an `errors` map keyed by field (shape validation) or a domain `error_code` — including manual_official_rate_value_date_too_far_in_future when effective_date exceeds Caracas today + 5 days", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "error_code": { "type": "string", "nullable": true, "enum": [ "manual_official_rate_effective_date_required", "manual_official_rate_quote_must_be_ves", "manual_official_rate_base_currency_not_allowed", "manual_official_rate_value_date_too_far_in_future" ] }, "errors": { "type": "object", "nullable": true } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/accounting/exchange-rates/official/for-document": { "get": { "tags": [ "Backoffice - Accounting - Exchange Rates" ], "summary": "The official rate a document of a given currency and date must take (membership only)", "description": "Applies ADR 0143: the first published value date on or after the document date. Reports absence with available=false instead of failing.", "operationId": "bfd34998727bb48e5ca46cd942159032", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "currency", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "USD", "VES" ] } }, { "name": "date", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "The rate the document takes, or an explicit absence", "content": { "application/json": { "schema": { "required": [ "currency", "date", "available", "rate", "value_date", "origin" ], "properties": { "currency": { "type": "string", "enum": [ "USD", "VES" ] }, "date": { "type": "string", "format": "date", "example": "2026-09-09" }, "available": { "type": "boolean" }, "rate": { "description": "Published pair rate (VES per USD) as a scale-8 decimal string; 1.00000000 when nothing converts", "type": "string", "example": "130.00000000", "nullable": true }, "value_date": { "type": "string", "format": "date", "example": "2026-09-09", "nullable": true }, "origin": { "type": "string", "nullable": true, "enum": [ "ingested", "manual" ] } }, "type": "object", "additionalProperties": false } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Authenticated but not a member of this tenant" }, "404": { "description": "Tenant does not exist (indistinguishable from missing route)" }, "422": { "description": "Invalid currency or date, or the company books in a currency outside the published set" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/accounting/exchange-rates/today": { "get": { "tags": [ "Backoffice - Accounting - Exchange Rates" ], "summary": "Today's official BCV rate for the tenant (membership only)", "operationId": "4f5c3272633288f9589916e2438728fc", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Whether official BCV rates apply, the latest USD/VES rate when present, and its freshness", "content": { "application/json": { "schema": { "required": [ "applicable", "rate", "freshness" ], "properties": { "applicable": { "type": "boolean" }, "rate": { "properties": { "value": { "type": "string", "example": "481.21770000" }, "effective_date": { "type": "string", "format": "date", "example": "2026-04-20" }, "first_seen_at": { "type": "string", "format": "date-time", "example": "2026-04-20T18:05:00+00:00" } }, "type": "object", "nullable": true, "additionalProperties": false }, "freshness": { "description": "Null when applicable is false (the company's country does not use official BCV rates)", "required": [ "state", "last_value_date", "origin" ], "properties": { "state": { "type": "string", "enum": [ "fresh", "late", "blocked" ] }, "last_value_date": { "type": "string", "format": "date", "example": "2026-04-20", "nullable": true }, "origin": { "type": "string", "nullable": true, "enum": [ "ingested", "manual" ] } }, "type": "object", "nullable": true, "additionalProperties": false } }, "type": "object", "additionalProperties": false } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Authenticated but not a member of this tenant" }, "404": { "description": "Tenant does not exist (indistinguishable from missing route)" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/accounting/fx-revaluations/{month}": { "post": { "tags": [ "Backoffice - Accounting - Fx Revaluations" ], "summary": "Propose the month's exchange revaluation as draft manual entries", "description": "Creates up to two draft `fx_revaluation` Manual Entries for the month (treasury without reverse_on; control with reverse_on = day 1 of the next month). Empty proposals answer 200 with `drafts: []`; non-empty ones answer 201. Requires `backoffice.accounting.manual-entries.create`.", "operationId": "proposeFxRevaluation", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "month", "in": "path", "description": "The month, YYYY-MM", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$", "example": "2026-09" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "policy_reference" ], "properties": { "policy_reference": { "type": "string", "example": "Política de revaluación al cierre, tasa BCV", "maxLength": 255, "minLength": 1 }, "description": { "description": "Defaults to Revaluación cambiaria {YYYY-MM} when omitted", "type": "string", "nullable": true, "maxLength": 255 } }, "type": "object" } } } }, "responses": { "201": { "description": "Drafts created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FxRevaluationProposeResult" } } } }, "200": { "description": "No lines to propose; nothing was written", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FxRevaluationProposeResult" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks the create permission" }, "409": { "description": "A draft fx_revaluation is already pending in the month: fx_revaluation_draft_pending", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FxRevaluationProblem" } } } }, "422": { "description": "Validation error, a business rule refused the proposal, or a Manual Entry line refusal (1-based `position`; field path `lines.N` is proposal line order, 0-based in `errors` keys)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FxRevaluationProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/accounting/fx-revaluations/{month}/preview": { "get": { "tags": [ "Backoffice - Accounting - Fx Revaluations" ], "summary": "Preview the month's exchange revaluation proposal", "description": "Computes the month-end foreign-currency revaluation deltas per (account, center, original currency) and returns them grouped as treasury (accumulates) and control (reverses on day 1 of the next month), without writing. Requires `backoffice.accounting.manual-entries.create`.", "operationId": "previewFxRevaluation", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "month", "in": "path", "description": "The month, YYYY-MM", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$", "example": "2026-09" } } ], "responses": { "200": { "description": "The proposal preview", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FxRevaluationPreview" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks the create permission" }, "409": { "description": "A draft fx_revaluation is already pending in the month: fx_revaluation_draft_pending", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FxRevaluationProblem" } } } }, "422": { "description": "Validation error, or a business rule refused the preview (month_not_ended, accounting_period_closed, closing_rate_unavailable, posting_account_role_missing)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FxRevaluationProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/accounting/ledger-reports/balance-sheet/export": { "get": { "tags": [ "Ledger Reports" ], "summary": "Exportar balance general", "operationId": "d540c19596c91dddc50f926664255590", "parameters": [ { "$ref": "#/components/parameters/LedgerReportTenant" }, { "$ref": "#/components/parameters/LedgerReportDate" }, { "$ref": "#/components/parameters/LedgerReportBook" }, { "$ref": "#/components/parameters/LedgerReportCenter" } ], "responses": { "200": { "description": "Numeric XLSX attachment with identical rows and totals when every absolute amount is at most 9999999999999.99 and serialization preserves cents; otherwise 422", "headers": { "Cache-Control": { "description": "Always no-store: the workbook is never cached", "schema": { "type": "string", "example": "no-store, private" } } }, "content": { "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Unauthenticated before controller execution", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LedgerReportMessageError" } } } }, "403": { "description": "Report permission or tenant membership denied", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/LedgerReportForbiddenError" }, { "$ref": "#/components/schemas/LedgerReportProblem" } ] } } } }, "404": { "description": "An unknown company in the path, answered by the tenant middleware with a message, or company_not_found when the report cannot read the company's record", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/LedgerReportMessageError" }, { "$ref": "#/components/schemas/LedgerReportProblem" } ] } } } }, "422": { "description": "FormRequest validation or controller/domain invalid date, range, book or company-scoped center; unsafe numeric XLSX amounts return ledger_report_excel_precision_exceeded before any attachment", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/LedgerReportValidationError" }, { "$ref": "#/components/schemas/LedgerReportProblem" } ] } } } }, "503": { "description": "Ledger query temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LedgerReportProblem" } } } }, "500": { "description": "Unexpected internal failure, or a tenant route that lost its company (TenantCompanyMissing)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LedgerReportProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/accounting/ledger-reports/balance-sheet": { "get": { "tags": [ "Ledger Reports" ], "summary": "Balance general", "operationId": "5dfbaffac751b687b01ffd7c96e2dc98", "parameters": [ { "$ref": "#/components/parameters/LedgerReportTenant" }, { "$ref": "#/components/parameters/LedgerReportDate" }, { "$ref": "#/components/parameters/LedgerReportBook" }, { "$ref": "#/components/parameters/LedgerReportCenter" } ], "responses": { "200": { "description": "Exact decimal financial report", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BalanceSheet" } } } }, "401": { "description": "Unauthenticated before controller execution", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LedgerReportMessageError" } } } }, "403": { "description": "Report permission or tenant membership denied", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/LedgerReportForbiddenError" }, { "$ref": "#/components/schemas/LedgerReportProblem" } ] } } } }, "404": { "description": "An unknown company in the path, answered by the tenant middleware with a message, or company_not_found when the report cannot read the company's record", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/LedgerReportMessageError" }, { "$ref": "#/components/schemas/LedgerReportProblem" } ] } } } }, "422": { "description": "FormRequest validation or controller/domain invalid date, range, book or company-scoped center", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/LedgerReportValidationError" }, { "$ref": "#/components/schemas/LedgerReportProblem" } ] } } } }, "503": { "description": "Ledger query temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LedgerReportProblem" } } } }, "500": { "description": "Unexpected internal failure, or a tenant route that lost its company (TenantCompanyMissing)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LedgerReportProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/accounting/ledger-reports/general-ledger/export": { "get": { "tags": [ "Ledger Reports" ], "summary": "Exportar mayor analítico", "operationId": "ce144151dae2285d7c62bcb4c7bf6180", "parameters": [ { "$ref": "#/components/parameters/LedgerReportTenant" }, { "$ref": "#/components/parameters/GeneralLedgerAccountId" }, { "$ref": "#/components/parameters/GeneralLedgerIncludeSubtree" }, { "$ref": "#/components/parameters/LedgerReportFrom" }, { "$ref": "#/components/parameters/LedgerReportTo" }, { "$ref": "#/components/parameters/LedgerReportBook" }, { "$ref": "#/components/parameters/LedgerReportCenter" } ], "responses": { "200": { "description": "Complete selected period, independent of pagination; at most 10000 lines. Numeric XLSX requires every emitted absolute amount at most 9999999999999.99 and actual serializer cent parity. Any page query is prohibited.", "headers": { "Cache-Control": { "description": "Always no-store: the workbook is never cached", "schema": { "type": "string", "example": "no-store, private" } } }, "content": { "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Unauthenticated before controller execution", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LedgerReportMessageError" } } } }, "403": { "description": "Report permission or tenant membership denied", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/LedgerReportForbiddenError" }, { "$ref": "#/components/schemas/LedgerReportProblem" } ] } } } }, "404": { "description": "An unknown company in the path, answered by the tenant middleware with a message; company_not_found when the report cannot read the company's record; or ledger_report_account_not_found when the selected account is deleted after validation", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/LedgerReportMessageError" }, { "$ref": "#/components/schemas/LedgerReportProblem" } ] } } } }, "422": { "description": "Validation, prohibited page, ledger_report_too_large with exact line_count/max_lines, or ledger_report_excel_precision_exceeded. No error carries an attachment.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/LedgerReportValidationError" }, { "$ref": "#/components/schemas/LedgerReportProblem" }, { "$ref": "#/components/schemas/LedgerReportTooLargeProblem" } ] } } } }, "503": { "description": "Ledger/catalog/source/snapshot query temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LedgerReportProblem" } } } }, "500": { "description": "Malformed persisted mandatory facts, an unexpected internal failure, or a tenant route that lost its company (TenantCompanyMissing)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LedgerReportProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/accounting/ledger-reports/general-ledger": { "get": { "tags": [ "Ledger Reports" ], "summary": "Mayor analítico", "operationId": "3a17abf9e40ad2d5fcf60b609b45e58a", "parameters": [ { "$ref": "#/components/parameters/LedgerReportTenant" }, { "$ref": "#/components/parameters/GeneralLedgerAccountId" }, { "$ref": "#/components/parameters/GeneralLedgerIncludeSubtree" }, { "$ref": "#/components/parameters/LedgerReportFrom" }, { "$ref": "#/components/parameters/LedgerReportTo" }, { "$ref": "#/components/parameters/LedgerReportBook" }, { "$ref": "#/components/parameters/LedgerReportCenter" }, { "$ref": "#/components/parameters/GeneralLedgerPage" } ], "responses": { "200": { "description": "Exact scale-2 strings; fixed 200-line page ordered by item date, entry code and line ID. Complete-period totals and closing; overflow returns empty rows, full closing carry and is_out_of_range=true. One repeatable-read snapshot per response; separate requests may observe later postings.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralLedgerDetail" } } } }, "401": { "description": "Unauthenticated before controller execution", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LedgerReportMessageError" } } } }, "403": { "description": "Report permission or tenant membership denied", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/LedgerReportForbiddenError" }, { "$ref": "#/components/schemas/LedgerReportProblem" } ] } } } }, "404": { "description": "Missing tenant/company or selected account deleted after validation", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/LedgerReportMessageError" }, { "$ref": "#/components/schemas/LedgerReportProblem" } ] } } } }, "422": { "description": "Validation of required company-owned historical account, subtree boolean, strict dates/range, book, company-owned historical center or bounded decimal integer page", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/LedgerReportValidationError" }, { "$ref": "#/components/schemas/LedgerReportProblem" } ] } } } }, "503": { "description": "Ledger/catalog/source/snapshot query temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LedgerReportProblem" } } } }, "500": { "description": "Malformed persisted mandatory facts or unexpected internal failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LedgerReportProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/accounting/ledger-reports/income-statement/export": { "get": { "tags": [ "Ledger Reports" ], "summary": "Exportar estado de resultados", "operationId": "0f1f2d80016e0995eb8e5b3af3f4cf6a", "parameters": [ { "$ref": "#/components/parameters/LedgerReportTenant" }, { "$ref": "#/components/parameters/LedgerReportFrom" }, { "$ref": "#/components/parameters/LedgerReportTo" }, { "$ref": "#/components/parameters/LedgerReportBook" }, { "$ref": "#/components/parameters/LedgerReportCenter" } ], "responses": { "200": { "description": "Numeric XLSX attachment with identical rows and totals when every absolute amount is at most 9999999999999.99 and serialization preserves cents; otherwise 422", "headers": { "Cache-Control": { "description": "Always no-store: the workbook is never cached", "schema": { "type": "string", "example": "no-store, private" } } }, "content": { "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Unauthenticated before controller execution", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LedgerReportMessageError" } } } }, "403": { "description": "Report permission or tenant membership denied", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/LedgerReportForbiddenError" }, { "$ref": "#/components/schemas/LedgerReportProblem" } ] } } } }, "404": { "description": "An unknown company in the path, answered by the tenant middleware with a message, or company_not_found when the report cannot read the company's record", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/LedgerReportMessageError" }, { "$ref": "#/components/schemas/LedgerReportProblem" } ] } } } }, "422": { "description": "FormRequest validation or controller/domain invalid date, range, book or company-scoped center; unsafe numeric XLSX amounts return ledger_report_excel_precision_exceeded before any attachment", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/LedgerReportValidationError" }, { "$ref": "#/components/schemas/LedgerReportProblem" } ] } } } }, "503": { "description": "Ledger query temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LedgerReportProblem" } } } }, "500": { "description": "Unexpected internal failure, or a tenant route that lost its company (TenantCompanyMissing)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LedgerReportProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/accounting/ledger-reports/income-statement": { "get": { "tags": [ "Ledger Reports" ], "summary": "Estado de resultados", "operationId": "eadad40dd67998001f96d59ef01983de", "parameters": [ { "$ref": "#/components/parameters/LedgerReportTenant" }, { "$ref": "#/components/parameters/LedgerReportFrom" }, { "$ref": "#/components/parameters/LedgerReportTo" }, { "$ref": "#/components/parameters/LedgerReportBook" }, { "$ref": "#/components/parameters/LedgerReportCenter" } ], "responses": { "200": { "description": "Exact decimal financial report", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IncomeStatement" } } } }, "401": { "description": "Unauthenticated before controller execution", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LedgerReportMessageError" } } } }, "403": { "description": "Report permission or tenant membership denied", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/LedgerReportForbiddenError" }, { "$ref": "#/components/schemas/LedgerReportProblem" } ] } } } }, "404": { "description": "An unknown company in the path, answered by the tenant middleware with a message, or company_not_found when the report cannot read the company's record", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/LedgerReportMessageError" }, { "$ref": "#/components/schemas/LedgerReportProblem" } ] } } } }, "422": { "description": "FormRequest validation or controller/domain invalid date, range, book or company-scoped center", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/LedgerReportValidationError" }, { "$ref": "#/components/schemas/LedgerReportProblem" } ] } } } }, "503": { "description": "Ledger query temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LedgerReportProblem" } } } }, "500": { "description": "Unexpected internal failure, or a tenant route that lost its company (TenantCompanyMissing)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LedgerReportProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/accounting/ledger-reports/journal/export": { "get": { "tags": [ "Ledger Reports" ], "summary": "Exportar libro diario", "operationId": "b5823169b641a056bedf1e2d7a9e8064", "parameters": [ { "$ref": "#/components/parameters/LedgerReportTenant" }, { "$ref": "#/components/parameters/JournalFrom" }, { "$ref": "#/components/parameters/JournalTo" }, { "$ref": "#/components/parameters/LedgerReportBook" }, { "$ref": "#/components/parameters/JournalCenter" } ], "responses": { "200": { "description": "Complete selected period, independent of pagination; at most 10000 lines. Numeric XLSX requires every emitted absolute amount at most 9999999999999.99 and actual serializer cent parity. Any page query is prohibited.", "headers": { "Cache-Control": { "description": "Always no-store: the workbook is never cached", "schema": { "type": "string", "example": "no-store, private" } } }, "content": { "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Unauthenticated before controller execution", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LedgerReportMessageError" } } } }, "403": { "description": "Report permission or tenant membership denied", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/LedgerReportForbiddenError" }, { "$ref": "#/components/schemas/LedgerReportProblem" } ] } } } }, "404": { "description": "An unknown company in the path, answered by the tenant middleware with a message, or company_not_found when the report cannot read the company's record", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/LedgerReportMessageError" }, { "$ref": "#/components/schemas/LedgerReportProblem" } ] } } } }, "422": { "description": "Validation, prohibited page, ledger_report_too_large with exact line_count/max_lines, or ledger_report_excel_precision_exceeded. No error carries an attachment.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/LedgerReportValidationError" }, { "$ref": "#/components/schemas/LedgerReportProblem" }, { "$ref": "#/components/schemas/LedgerReportTooLargeProblem" } ] } } } }, "503": { "description": "Ledger/catalog/source/snapshot query temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LedgerReportProblem" } } } }, "500": { "description": "Malformed persisted mandatory facts, an unexpected internal failure, or a tenant route that lost its company (TenantCompanyMissing)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LedgerReportProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/accounting/ledger-reports/journal": { "get": { "tags": [ "Ledger Reports" ], "summary": "Libro diario", "operationId": "256f071b254371c920805acf8fa882db", "parameters": [ { "$ref": "#/components/parameters/LedgerReportTenant" }, { "$ref": "#/components/parameters/JournalFrom" }, { "$ref": "#/components/parameters/JournalTo" }, { "$ref": "#/components/parameters/LedgerReportBook" }, { "$ref": "#/components/parameters/JournalCenter" }, { "$ref": "#/components/parameters/JournalPage" } ], "responses": { "200": { "description": "Exact scale-2 strings; fixed 50 distinct headers ordered by authentic header date/code/ID; every selected line ordered by line date/ID. Line dates and optional center select financial membership; partial entries may differ in debits and credits. Full-range counts/totals survive overflow. One repeatable-read snapshot per response; source availability does not grant native document permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Journal" } } } }, "401": { "description": "Unauthenticated before controller execution", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LedgerReportMessageError" } } } }, "403": { "description": "Report permission or tenant membership denied", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/LedgerReportForbiddenError" }, { "$ref": "#/components/schemas/LedgerReportProblem" } ] } } } }, "404": { "description": "Missing tenant/company", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/LedgerReportMessageError" }, { "$ref": "#/components/schemas/LedgerReportProblem" } ] } } } }, "422": { "description": "Validation of strict inclusive line dates/range, book, company-owned historical center or bounded decimal integer page", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/LedgerReportValidationError" }, { "$ref": "#/components/schemas/LedgerReportProblem" } ] } } } }, "503": { "description": "Ledger/catalog/source/snapshot query temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LedgerReportProblem" } } } }, "500": { "description": "Malformed persisted mandatory facts or unexpected internal failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LedgerReportProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/accounting/ledger-reports/trial-balance/export": { "get": { "tags": [ "Ledger Reports" ], "summary": "Exportar balance de comprobación", "operationId": "51bc09d9bf3627c67089b6a1a19f3c49", "parameters": [ { "$ref": "#/components/parameters/LedgerReportTenant" }, { "$ref": "#/components/parameters/LedgerReportFrom" }, { "$ref": "#/components/parameters/LedgerReportTo" }, { "$ref": "#/components/parameters/LedgerReportBook" }, { "$ref": "#/components/parameters/LedgerReportCenter" }, { "$ref": "#/components/parameters/LedgerReportIncludeZero" } ], "responses": { "200": { "description": "Numeric XLSX attachment with identical rows and totals when every absolute amount is at most 9999999999999.99 and serialization preserves cents; otherwise 422", "headers": { "Cache-Control": { "description": "Always no-store: the workbook is never cached", "schema": { "type": "string", "example": "no-store, private" } } }, "content": { "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Unauthenticated before controller execution", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LedgerReportMessageError" } } } }, "403": { "description": "Report permission or tenant membership denied", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/LedgerReportForbiddenError" }, { "$ref": "#/components/schemas/LedgerReportProblem" } ] } } } }, "404": { "description": "An unknown company in the path, answered by the tenant middleware with a message, or company_not_found when the report cannot read the company's record", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/LedgerReportMessageError" }, { "$ref": "#/components/schemas/LedgerReportProblem" } ] } } } }, "422": { "description": "FormRequest validation or controller/domain invalid date, range, book, boolean or company-scoped center; unsafe numeric XLSX amounts return ledger_report_excel_precision_exceeded before any attachment", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/LedgerReportValidationError" }, { "$ref": "#/components/schemas/LedgerReportProblem" } ] } } } }, "503": { "description": "Ledger query temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LedgerReportProblem" } } } }, "500": { "description": "Unexpected internal failure, or a tenant route that lost its company (TenantCompanyMissing)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LedgerReportProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/accounting/ledger-reports/trial-balance": { "get": { "tags": [ "Ledger Reports" ], "summary": "Balance de comprobación", "operationId": "664f5eae85afd83c3bba18d2447a4314", "parameters": [ { "$ref": "#/components/parameters/LedgerReportTenant" }, { "$ref": "#/components/parameters/LedgerReportFrom" }, { "$ref": "#/components/parameters/LedgerReportTo" }, { "$ref": "#/components/parameters/LedgerReportBook" }, { "$ref": "#/components/parameters/LedgerReportCenter" }, { "$ref": "#/components/parameters/LedgerReportIncludeZero" } ], "responses": { "200": { "description": "Exact decimal financial report", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrialBalance" } } } }, "401": { "description": "Unauthenticated before controller execution", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LedgerReportMessageError" } } } }, "403": { "description": "Report permission or tenant membership denied", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/LedgerReportForbiddenError" }, { "$ref": "#/components/schemas/LedgerReportProblem" } ] } } } }, "404": { "description": "An unknown company in the path, answered by the tenant middleware with a message, or company_not_found when the report cannot read the company's record", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/LedgerReportMessageError" }, { "$ref": "#/components/schemas/LedgerReportProblem" } ] } } } }, "422": { "description": "FormRequest validation or controller/domain invalid date, range, book, boolean or company-scoped center", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/LedgerReportValidationError" }, { "$ref": "#/components/schemas/LedgerReportProblem" } ] } } } }, "503": { "description": "Ledger query temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LedgerReportProblem" } } } }, "500": { "description": "Unexpected internal failure, or a tenant route that lost its company (TenantCompanyMissing)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LedgerReportProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/accounting/manual-entries": { "get": { "tags": [ "Backoffice - Accounting - Manual Entries" ], "summary": "Search the company's manual entries", "description": "Lists the company's manual entries, newest accounting date first, each with its totals per book and who registered and approved it; the lines are on the detail. A company without entries returns an empty `items` list with `total` 0. Requires `backoffice.accounting.manual-entries.view`.", "operationId": "searchManualEntries", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "draft", "approved", "cancelled" ] } }, { "name": "purpose", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "adjustment", "provision", "reclassification", "fx_revaluation", "tax_settlement" ] } }, { "name": "from", "in": "query", "description": "Inclusive accounting date.", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "description": "Inclusive accounting date; not before `from` when both are sent.", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 15, "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "A page of manual entries", "content": { "application/json": { "schema": { "required": [ "items", "total", "per_page", "current_page" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ManualEntrySummary" } }, "total": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 15 }, "current_page": { "type": "integer", "example": 1 } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks the view permission" }, "422": { "description": "Invalid filter or pagination parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualEntryProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Accounting - Manual Entries" ], "summary": "Register a draft manual entry", "description": "Registers a draft manual entry under the next `AM` code of the year, recording the user who registered it. A draft is not posted and may not balance yet: balance and control-account neutrality are checked on approval. Each line posts to an active accounting account and an active accounting center of the company; a book kept in the line's original currency posts its original amount, and when both books keep one currency they post the same amount. The date may not be after the company's today; `policy_reference` is required for `fx_revaluation`; the optional `reverse_on` schedules its reversal for a day of the following month. The client generates the UUID `id`: resending the same id with the same terms answers 200 with the entry as it stands and writes nothing; with other terms 409 manual_entry_id_conflict. Refusals answered by the request validator (422, `error_code` null, the field under `errors`): a missing or malformed field, including a blank or too long `description`, `source_reference`, `policy_reference` or `memo`, a missing `policy_reference` for `fx_revaluation`, fewer than 2 or more than 500 `lines`, an amount that is not a decimal string with at most 2 decimals, and a `date` or `reverse_on` that is not a YYYY-MM-DD calendar date. Refusals answered by the domain (422 with `error_code`): manual_entry_date_in_future; manual_entry_reverse_on_out_of_range when `reverse_on` is not a day of the calendar month after `date`; and the line refusals manual_entry_line_without_amount, manual_entry_line_amount_mismatch, manual_entry_line_rate_out_of_range, manual_entry_line_account_invalid and manual_entry_line_center_invalid, which carry the line's 1-based `position` (and `book` for a mismatch or a rate out of range) with the offending field under `errors`. The domain codes manual_entry_text_out_of_range, manual_entry_policy_reference_required, manual_entry_line_count_out_of_range, manual_entry_invalid_amount and manual_entry_invalid_date guard the same rules behind the validator and are not expected on the wire. Requires `backoffice.accounting.manual-entries.create`.", "operationId": "registerManualEntry", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualEntryRegisterRequest" } } } }, "responses": { "201": { "description": "Draft registered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualEntryWriteResult" } } } }, "200": { "description": "The same id was already registered with the same terms; nothing was written and the entry is answered as it stands", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualEntryWriteResult" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks the create permission" }, "404": { "description": "The company does not exist (company_not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualEntryProblem" } } } }, "409": { "description": "The id is already used by an entry with other terms: manual_entry_id_conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualEntryProblem" } } } }, "422": { "description": "Validation error, or a business rule refused the draft", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualEntryProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/accounting/manual-entries/{id}/approve": { "post": { "tags": [ "Backoffice - Accounting - Manual Entries" ], "summary": "Approve a draft manual entry and post it", "description": "Approves a draft manual entry and, in the same step, posts its `manual_entry.approved` ledger entry on the entry's date, linked to it (`linkable_type` manual_entry), one ledger line per entry line at the amounts captured in each book; the rates it stores only describe those amounts. Its lines are checked again against the books the company keeps now (422 manual_entry_line_amount_mismatch or manual_entry_line_rate_out_of_range with the line's `position` and `book`). It must balance exactly in the functional and in the reporting book: otherwise 422 manual_entry_unbalanced with `functional_difference` and `reporting_difference` (debit total minus credit total, signed) and the `unbalanced_books`. Its lines on each receivable or payable control account must net to zero per account and book, whatever their centers, unless the entry carries `reverse_on`: then the same step also posts `manual_entry.reversed` dated `reverse_on`, inverting every approved line in both books and linked to the approved entry. Otherwise 422 manual_entry_control_account_not_neutral naming the `account_ids`. An entry dated in a closed accounting period is refused with `{error: accounting_configuration_incomplete, missing[]}` (reason ACCOUNTING_PERIOD_CLOSED) and nothing is written. An entry that is no longer a draft answers 409 manual_entry_not_approvable. The approver and the time are recorded and the approval is written to the audit log. Requires `backoffice.accounting.manual-entries.approve`, which the create permission does not imply.", "operationId": "approveManualEntry", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Entry approved and posted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualEntryWriteResult" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks the approve permission" }, "404": { "description": "The company holds no such manual entry (manual_entry_not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualEntryProblem" } } } }, "409": { "description": "The entry is no longer a draft: manual_entry_not_approvable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualEntryProblem" } } } }, "422": { "description": "A malformed id, an entry that does not balance or leaves a control account moved, a line its books contradict, or a closed accounting period", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualEntryProblem" } } } }, "500": { "description": "The ledger could not post the entry or its reversal (invalid_transaction_balance, empty_transaction_items, transaction_persistence_failed, manual_entry_posted_transaction_missing or transaction_already_reversed)" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/accounting/manual-entries/{id}/cancel": { "post": { "tags": [ "Backoffice - Accounting - Manual Entries" ], "summary": "Cancel a manual entry", "description": "Cancels a manual entry with a reason. A draft becomes cancelled and nothing is posted. An approved entry becomes cancelled and, in the same step, posts `manual_entry.cancelled` dated the company's today, inverting every line of its `manual_entry.approved` entry in both books and linked to it. An approved entry that carries a Scheduled Reversal was reversed when it was approved and cannot be cancelled: 409 manual_entry_already_reversed; correct it with a new entry. A cancelled entry answers 409 manual_entry_already_cancelled. A blank reason, or one longer than 500 characters once trimmed, answers the validator's 422 with `errors.reason` (the domain's manual_entry_cancel_reason_invalid guards the same rule and is not expected on the wire). Who cancelled it, when and why are recorded and the cancellation is written to the audit log as `backoffice.accounting.manual-entries.cancelled` with its reason. Requires `backoffice.accounting.manual-entries.cancel`, which no other manual entry permission implies.", "operationId": "cancelManualEntry", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualEntryCancelRequest" } } } }, "responses": { "200": { "description": "Entry cancelled; an approved one's posting is mirrored", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualEntryWriteResult" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks the cancel permission" }, "404": { "description": "The company holds no such manual entry (manual_entry_not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualEntryProblem" } } } }, "409": { "description": "The entry is already cancelled (manual_entry_already_cancelled), or it is approved and its Scheduled Reversal was posted (manual_entry_already_reversed)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualEntryProblem" } } } }, "422": { "description": "A malformed id (errors.id) or a blank or too long reason (errors.reason), answered by the request validator", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualEntryProblem" } } } }, "500": { "description": "The ledger could not mirror the approved entry (manual_entry_posted_transaction_missing, transaction_already_reversed, invalid_transaction_balance, empty_transaction_items or transaction_persistence_failed)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualEntryProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/accounting/manual-entries/{id}": { "get": { "tags": [ "Backoffice - Accounting - Manual Entries" ], "summary": "Show a manual entry", "description": "Shows a manual entry of the company with its lines in position order, who registered and who approved it, and the ledger entries it posted (empty for a draft). Requires `backoffice.accounting.manual-entries.view`.", "operationId": "findManualEntry", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The manual entry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualEntry" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks the view permission" }, "404": { "description": "The company holds no such manual entry (manual_entry_not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualEntryProblem" } } } }, "422": { "description": "The id is not a UUID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualEntryProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Backoffice - Accounting - Manual Entries" ], "summary": "Revise a draft manual entry", "description": "Replaces every term of a draft manual entry — date, purpose, texts, `reverse_on` and lines — under the rules of its registration, keeping its code. An entry that is no longer a draft is refused with 409 manual_entry_not_editable before its new terms are read. Refusals answered by the request validator (422, `error_code` null, the field under `errors`): a missing or malformed field, including a blank or too long `description`, `source_reference`, `policy_reference` or `memo`, a missing `policy_reference` for `fx_revaluation`, fewer than 2 or more than 500 `lines`, an amount that is not a decimal string with at most 2 decimals, and a `date` or `reverse_on` that is not a YYYY-MM-DD calendar date. Refusals answered by the domain (422 with `error_code`): manual_entry_date_in_future; manual_entry_reverse_on_out_of_range when `reverse_on` is not a day of the calendar month after `date`; and the line refusals manual_entry_line_without_amount, manual_entry_line_amount_mismatch, manual_entry_line_rate_out_of_range, manual_entry_line_account_invalid and manual_entry_line_center_invalid, which carry the line's 1-based `position` (and `book` for a mismatch or a rate out of range) with the offending field under `errors`. The domain codes manual_entry_text_out_of_range, manual_entry_policy_reference_required, manual_entry_line_count_out_of_range, manual_entry_invalid_amount and manual_entry_invalid_date guard the same rules behind the validator and are not expected on the wire. Requires `backoffice.accounting.manual-entries.create`.", "operationId": "reviseManualEntryDraft", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualEntryReviseRequest" } } } }, "responses": { "200": { "description": "Draft revised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualEntryWriteResult" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks the create permission" }, "404": { "description": "The company holds no such manual entry (manual_entry_not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualEntryProblem" } } } }, "409": { "description": "The entry is no longer a draft: manual_entry_not_editable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualEntryProblem" } } } }, "422": { "description": "Validation error, a malformed id, or a business rule refused the terms", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualEntryProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/accounting/month-end-closes/{month}": { "get": { "tags": [ "Backoffice - Accounting - Month-End Closes" ], "summary": "Show a month's close checklist", "description": "Runs the month-end close checklist for one month now (ADR 0269) and shows its findings, its accounting period's status, its fiscal periods for a company with a configured fiscal profile and its latest close. A blocking finding, such as documents or manual entries dated in the month still waiting for approval, refuses the close; a warning closes only with a justification; an informative finding, such as an accounting period already closed, only informs. Nothing is locked or stored. Requires `backoffice.accounting.month-end-closes.view`.", "operationId": "findMonthEndClose", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "month", "in": "path", "description": "The month, YYYY-MM", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$", "example": "2026-09" } } ], "responses": { "200": { "description": "The month's checklist", "content": { "application/json": { "schema": { "required": [ "month", "accounting_period_status", "fiscal_periods", "findings", "close" ], "properties": { "month": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$", "example": "2026-09" }, "accounting_period_status": { "description": "Closed when the month falls on or before the closed-through month.", "type": "string", "example": "open", "enum": [ "open", "closed" ] }, "fiscal_periods": { "description": "The month's fiscal periods, oldest first: the month alone or its two fortnights, whose in-review ones the close closes with the accounting period. [] when the company has no configured fiscal profile, so the close leaves its fiscal periods to the fiscal periods screen.", "type": "array", "items": { "required": [ "period", "status" ], "properties": { "period": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])(-[12])?$", "example": "2026-09-2" }, "status": { "description": "Open when the period was never frozen.", "type": "string", "example": "in_review", "enum": [ "open", "in_review", "closed" ] } }, "type": "object" } }, "findings": { "description": "In checklist order; [] when nothing was found.", "type": "array", "items": { "$ref": "#/components/schemas/CloseFinding" } }, "close": { "description": "The month's latest close; null when it was never closed through the month-end close.", "type": "object", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/MonthEndClose" } ] } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks the view permission" }, "422": { "description": "The month is not a YYYY-MM month (errors.month)", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string", "example": "The given data was invalid." }, "error_code": { "type": "string", "example": null, "nullable": true }, "errors": { "type": "object", "nullable": true } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/accounting/month-end-closes/{month}/close": { "post": { "tags": [ "Backoffice - Accounting - Month-End Closes" ], "summary": "Close a month", "description": "Runs the month-end close (ADR 0269): in one transaction it re-runs the checklist, refuses any blocking finding, requires a justification for each warning, then, for a company with a configured fiscal profile, closes the month's fiscal periods in review, oldest first (each audited as `backoffice.fiscal.fiscal-periods.closed`), then closes the month's accounting period under its own rules (ADR 0235) and records the findings, the justifications, the fiscal periods it closed, who closed it and when. A refusal of either close leaves both periods as they were. The close is audited as `backoffice.accounting.month-end-closes.closed`. Justifications offered for anything other than a current warning are dropped. Requires `backoffice.accounting.month-end-closes.close`, which covers the fiscal close.", "operationId": "closeMonth", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "month", "in": "path", "description": "The month to close, YYYY-MM", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$", "example": "2026-09" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "justifications": { "description": "The justification of each warning, keyed by its finding code (UPPER_SNAKE_CASE, at most 64 characters). Surrounding whitespace is trimmed first and the 1 to 500 characters are counted on what remains; inner line breaks are kept and a blank text is refused. Absent when no warning is justified.", "maxProperties": 50, "type": "object", "example": { "TEST_WARNING": "Anticipo documentado en el expediente 12." }, "additionalProperties": { "type": "string", "maxLength": 500, "minLength": 1 } } }, "type": "object" } } } }, "responses": { "201": { "description": "The month is closed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonthEndClose" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks the close permission" }, "404": { "description": "The company does not exist (company_not_found)", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "detail": { "type": "string" }, "error_code": { "type": "string", "example": "company_not_found" } }, "type": "object" } } } }, "409": { "description": "The month's accounting period is on or before the closed-through month (accounting_period_already_closed); a fiscal period of the month changed status while it closed (fiscal_period_status_conflict); or another request changed the company's fiscal periods at the same time, so reload and retry (fiscal_period_concurrent_write)", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "detail": { "type": "string", "example": "El período contable <2026-09> ya está cerrado; los meses de la empresa están cerrados hasta <2026-09>" }, "error_code": { "type": "string", "example": "accounting_period_already_closed", "enum": [ "accounting_period_already_closed", "fiscal_period_status_conflict", "fiscal_period_concurrent_write" ] } }, "type": "object" } } } }, "422": { "description": "The month or a justification is malformed (errors.month, errors.justifications, errors[\"justifications.CODE\"]); a blocking finding stands (month_close_blocked, with findings); a warning has no justification (month_close_justification_missing, with missing_justifications and findings); the month has not ended in the company's timezone (accounting_period_not_ended); it is not the month right after the closed-through month, which the detail names (accounting_period_out_of_order); or a fiscal period of the month is not of the type the company declares the month by (fiscal_period_type_mismatch)", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string", "example": "El mes <2026-09> no se puede cerrar mientras haya un hallazgo bloqueante: DOCUMENTS_PENDING_APPROVAL" }, "error_code": { "description": "Null on a validation error.", "type": "string", "example": "month_close_blocked", "nullable": true, "enum": [ "month_close_blocked", "month_close_justification_missing", "accounting_period_not_ended", "accounting_period_out_of_order", "fiscal_period_type_mismatch", "invalid_accounting_period_month", "invalid_month_close_justification", "invalid_close_finding_code" ] }, "errors": { "type": "object", "nullable": true }, "findings": { "description": "Every current finding; present on month_close_blocked and month_close_justification_missing.", "type": "array", "items": { "$ref": "#/components/schemas/CloseFinding" } }, "missing_justifications": { "description": "The warning codes left without a justification; present on month_close_justification_missing.", "type": "array", "items": { "type": "string", "example": "TEST_WARNING" } } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/accounting/month-end-closes": { "get": { "tags": [ "Backoffice - Accounting - Month-End Closes" ], "summary": "List the month-end closes of a range of months", "description": "Lists every stored month-end close of the months from `from` to `to`, inclusive, newest month first and then newest close first, with the findings and justifications each one recorded (ADR 0269). A close whose month's accounting period was reopened after it shows `reopened: true`; closing the month again adds a new close. Not paginated: a range holds a few closes per month. Requires `backoffice.accounting.month-end-closes.view`.", "operationId": "searchMonthEndCloses", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "description": "The first month, YYYY-MM", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$", "example": "2026-01" } }, { "name": "to", "in": "query", "description": "The last month, YYYY-MM, not before `from`", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$", "example": "2026-12" } } ], "responses": { "200": { "description": "The closes of the range", "content": { "application/json": { "schema": { "required": [ "items" ], "properties": { "items": { "description": "Newest month first, then newest close first.", "type": "array", "items": { "$ref": "#/components/schemas/MonthEndClose" } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks the view permission" }, "422": { "description": "`from` or `to` is missing or not a YYYY-MM month (errors.from, errors.to), or `to` is before `from` (errors.to)", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string", "example": "The given data was invalid." }, "error_code": { "type": "string", "example": null, "nullable": true }, "errors": { "type": "object", "nullable": true } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/accounting/opening-balances/{id}/confirm": { "post": { "tags": [ "Backoffice - Accounting - Opening Balances" ], "summary": "Confirm an Opening Balance draft", "operationId": "6f5f71314d7e73ee832c8531b92604a4", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "functional_currency", "reporting_currency" ], "properties": { "functional_currency": { "type": "string", "example": "VES" }, "reporting_currency": { "type": "string", "example": "USD" } }, "type": "object" } } } }, "responses": { "200": { "description": "Confirmed with posted transaction code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpeningBalanceReport" } } } }, "400": { "description": "Invalid currency or other typed domain input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpeningBalanceProblem" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpeningBalanceMessageError" } } } }, "403": { "description": "Route permission, API key scope, company or tenant membership refused", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/OpeningBalanceProblem" }, { "$ref": "#/components/schemas/OpeningBalanceMiddlewareProblem" } ] } } } }, "409": { "description": "Book acknowledgment, changed draft books requiring reupload, or active opening conflict", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/OpeningBalanceProblem" }, { "$ref": "#/components/schemas/OpeningBalanceMessageError" } ] } } } }, "422": { "description": "Committed refused report, controller validation, missing or changed source, import or other domain rejection", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/OpeningBalanceConfirmationProblem" }, { "$ref": "#/components/schemas/OpeningBalanceProblem" } ] } } } }, "404": { "description": "Draft not found, or company not found", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/OpeningBalanceProblem" }, { "$ref": "#/components/schemas/OpeningBalanceMessageError" } ] } } } }, "500": { "description": "Stored identity integrity failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpeningBalanceProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/accounting/opening-balances/current": { "get": { "tags": [ "Backoffice - Accounting - Opening Balances" ], "summary": "Get the current Opening Balance draft or confirmed opening with report", "operationId": "5d889db57004eb30911cc7f2c992b2a1", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Current opening with report", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpeningBalanceReport" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpeningBalanceMessageError" } } } }, "403": { "description": "Route permission, API key scope, company or tenant membership refused", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/OpeningBalanceProblem" }, { "$ref": "#/components/schemas/OpeningBalanceMiddlewareProblem" } ] } } } }, "404": { "description": "No draft or confirmed opening", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/OpeningBalanceProblem" }, { "$ref": "#/components/schemas/OpeningBalanceMessageError" } ] } } } }, "500": { "description": "Stored identity integrity failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpeningBalanceProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/accounting/opening-balances": { "post": { "tags": [ "Backoffice - Accounting - Opening Balances" ], "summary": "Upload an Opening Balance draft from an xlsx workbook", "operationId": "42837ff18658aa4cc0a17424b26b9c81", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "file", "opening_date", "opening_account_id", "functional_currency", "reporting_currency" ], "properties": { "file": { "description": "Opening balances xlsx", "type": "string", "format": "binary" }, "opening_date": { "type": "string", "format": "date", "example": "2026-09-01" }, "opening_account_id": { "type": "string", "format": "uuid" }, "functional_currency": { "type": "string", "example": "VES" }, "reporting_currency": { "type": "string", "example": "USD" } }, "type": "object" } } } }, "responses": { "201": { "description": "Draft created or replaced with report", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpeningBalanceReport" } } } }, "400": { "description": "Invalid currency or other typed domain input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpeningBalanceProblem" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpeningBalanceMessageError" } } } }, "403": { "description": "Route permission, API key scope, company or tenant membership refused", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/OpeningBalanceProblem" }, { "$ref": "#/components/schemas/OpeningBalanceMiddlewareProblem" } ] } } } }, "409": { "description": "Book pair or active opening conflict", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/OpeningBalanceProblem" }, { "$ref": "#/components/schemas/OpeningBalanceMessageError" } ] } } } }, "422": { "description": "Controller validation or import rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpeningBalanceProblem" } } } }, "404": { "description": "Company not found", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/OpeningBalanceProblem" }, { "$ref": "#/components/schemas/OpeningBalanceMessageError" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/accounting/opening-balances/{id}/reverse": { "post": { "tags": [ "Backoffice - Accounting - Opening Balances" ], "summary": "Reverse a confirmed Opening Balance", "operationId": "e9db39575e14ec0bfd79a993fdbd24d6", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Reversed" }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpeningBalanceMessageError" } } } }, "403": { "description": "Route permission, API key scope, company or tenant membership refused", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/OpeningBalanceProblem" }, { "$ref": "#/components/schemas/OpeningBalanceMiddlewareProblem" } ] } } } }, "404": { "description": "Opening not found for tenant, or opening_balance_no_active (already reversed / no confirmed opening)", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/OpeningBalanceProblem" }, { "$ref": "#/components/schemas/OpeningBalanceMessageError" } ] } } } }, "422": { "description": "Draft cannot be reversed, settlements block reverse, or controller validation", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/OpeningBalanceProblem" }, { "$ref": "#/components/schemas/OpeningBalanceMessageError" } ] } } } }, "500": { "description": "Unmapped integrity failure (for example TransactionAlreadyReversedError)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpeningBalanceProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/accounting/opening-balances/template": { "get": { "tags": [ "Backoffice - Accounting - Opening Balances" ], "summary": "Download the Opening Balance xlsx template", "description": "An Excel file with a «Saldos» sheet holding the seven opening balance columns and a «Documentos» sheet holding the seventeen open document columns, headers only.", "operationId": "29818453c2ae0eff2a5442f7845dc28c", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The template, as an attachment named plantilla-saldos-iniciales.xlsx", "headers": { "Content-Disposition": { "description": "Always this file name", "schema": { "type": "string", "example": "attachment; filename=\"plantilla-saldos-iniciales.xlsx\"" } }, "Cache-Control": { "description": "Always no-store: the workbook is never cached", "schema": { "type": "string", "example": "no-store, private" } } }, "content": { "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "format": "binary" } } } }, "403": { "description": "Problem JSON, title Forbidden. Without backoffice.accounting.opening-balances.view the route can: middleware answers with error_code and errors null; the tenant middleware stack (API-key guardrails, company access, tenant membership) answers without error_code, with a reason only from tenant membership.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ImportTemplateProblem" }, { "$ref": "#/components/schemas/ImportTemplateMiddlewareForbidden" } ] } } } }, "500": { "description": "Unexpected failure, reported. Problem JSON with error_code and errors null; the detail is generic in production.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportTemplateProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/accounting/payable-accounts/lookup": { "get": { "tags": [ "Backoffice - Accounting - Payable Account Lookups" ], "summary": "Lookup configured payable Accounting Accounts for tenant forms", "operationId": "d53eda8f0dda3e9024cbee453fcb1b7e", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "active", "inactive" ] } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 200, "minimum": 1 } } ], "responses": { "200": { "description": "Minimal configured payable Accounting Account projection", "content": { "application/json": { "schema": { "required": [ "items", "total", "per_page", "current_page" ], "properties": { "items": { "type": "array", "items": { "required": [ "id", "code", "name", "status", "default" ], "properties": { "id": { "description": "Underlying Accounting Account identifier", "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "default": { "description": "Whether this is the company's default payable account", "type": "boolean" } }, "type": "object" } }, "total": { "type": "integer" }, "per_page": { "type": "integer" }, "current_page": { "type": "integer" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Not a member of this tenant" }, "404": { "description": "Tenant not found" }, "422": { "description": "Invalid status filter" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/accounting/receivable-accounts/lookup": { "get": { "tags": [ "Backoffice - Accounting - Receivable Account Lookups" ], "summary": "Lookup active configured receivable Accounting Accounts for tenant forms", "operationId": "e1a84378b32099210a16180b67dce860", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 200, "minimum": 1 } } ], "responses": { "200": { "description": "Minimal active configured receivable Accounting Account projection", "content": { "application/json": { "schema": { "required": [ "items", "total", "per_page", "current_page" ], "properties": { "items": { "type": "array", "items": { "required": [ "id", "code", "name", "default" ], "properties": { "id": { "description": "Underlying Accounting Account identifier", "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "default": { "type": "boolean" } }, "type": "object" } }, "total": { "type": "integer" }, "per_page": { "type": "integer" }, "current_page": { "type": "integer" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Not a member of this tenant" }, "404": { "description": "Tenant not found" }, "422": { "description": "Invalid pagination" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/accounting/settings/inventory-in-transit-accounts/{id}": { "get": { "tags": [ "Backoffice - Accounting - Settings - Inventory In Transit Accounts" ], "summary": "Get an inventory in transit account of the company", "description": "Answers the list's row shape, with the code and name of the account and center, null when the reference does not resolve in the company. Another company's or an unknown id is 404. Requires `backoffice.accounting.settings.inventory-in-transit-accounts.view`.", "operationId": "735ff8b6d9efebb2084bbc254f4c341f", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The inventory in transit account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryInTransitAccount" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks the view permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountingSettingsProblem" } } } }, "404": { "description": "The account is not one of the company's. `error_code` is inventory_in_transit_account_not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountingSettingsProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Backoffice - Accounting - Settings - Inventory In Transit Accounts" ], "summary": "Update an inventory in transit account", "operationId": "4f19c986f2074eba218bc670cbba087d", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "account_id", "center_id", "status", "type" ], "properties": { "account_id": { "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440001" }, "center_id": { "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440002" }, "status": { "type": "string", "example": "active", "enum": [ "active", "inactive" ] }, "type": { "type": "string", "example": "ASSET", "enum": [ "ASSET", "LIABILITY" ] } }, "type": "object" } } } }, "responses": { "200": { "description": "Inventory in transit account updated successfully" }, "403": { "description": "The user lacks the update permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountingSettingsProblem" } } } }, "404": { "description": "The inventory in transit account is not one of the company's. `error_code` is inventory_in_transit_account_not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountingSettingsProblem" } } } }, "422": { "description": "Invalid fields, or an account or center that is not the company's, with `error_code` null and `errors` keyed by field; or a domain refusal placed on its field with its code: duplicate_active_inventory_in_transit_account on status when another active inventory in transit account of the company of its type exists, invalid_account_reference on account_id, invalid_center_reference on center_id. Nothing is modified.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountingSettingsProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Backoffice - Accounting - Settings - Inventory In Transit Accounts" ], "summary": "Delete an inventory in transit account", "operationId": "55267d803e7a1f43a4b94bcc6db2560c", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Inventory in transit account deleted successfully" }, "403": { "description": "The user lacks the delete permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountingSettingsProblem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Inventory in transit account not found" } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/accounting/settings/inventory-in-transit-accounts": { "get": { "tags": [ "Backoffice - Accounting - Settings - Inventory In Transit Accounts" ], "summary": "Search the company's inventory in transit accounts", "description": "Lists the company's inventory in transit accounts with the code and name of each one's accounting account and center, null when the reference does not resolve in the company. `status` and `type` take one value or several (`status=active` or `status[]=active&status[]=inactive`): values are alternatives within a field and both fields must match; `all` or an empty value is ignored. `search` matches the account's or the center's code or name literally, never the status or type text; it is trimmed and a blank term searches nothing. Without `sort_by` the order is the account's code ascending; a `sort_by` sent without `sort_order` reads descending, and a `sort_order` sent alone applies to the account's code. Ties are settled by id in the same direction. `group_by=status` lists active accounts before inactive ones, ahead of the requested order and before paging. `meta.counts` counts the matching accounts by status under every filter but `status`, zero-filled and independent of the page, its size, the order and the grouping. A blank parameter is ignored; unknown parameters are dropped; any other invalid value is a 422 on its parameter (`status.0` for the first status of a list). Requires `backoffice.accounting.settings.inventory-in-transit-accounts.view`; 403 precedes 422.", "operationId": "c6c714725714048d803a9e7bb3697ffa", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "description": "One status, or `all` for every status. Same as one `status[]`.", "required": false, "schema": { "type": "string", "enum": [ "active", "inactive", "all" ] } }, { "name": "status[]", "in": "query", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "active", "inactive" ] } } }, { "name": "type", "in": "query", "description": "One type, or `all` for every type. Same as one `type[]`.", "required": false, "schema": { "type": "string", "enum": [ "ASSET", "LIABILITY", "all" ] } }, { "name": "type[]", "in": "query", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "ASSET", "LIABILITY" ] } } }, { "name": "search", "in": "query", "description": "Matches the account's or the center's code or name, literally; trimmed, and blank searches nothing.", "required": false, "schema": { "type": "string", "maxLength": 255 } }, { "name": "sort_by", "in": "query", "required": false, "schema": { "type": "string", "default": "account_code", "enum": [ "account_code", "created_at" ] } }, { "name": "sort_order", "in": "query", "description": "Ascending when `sort_by` is omitted; descending when `sort_by` is sent without it. Trimmed, any case.", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "group_by", "in": "query", "description": "`status` lists active accounts first, before the requested order and before paging. `none` groups nothing.", "required": false, "schema": { "type": "string", "enum": [ "status", "none" ] } }, { "name": "page", "in": "query", "description": "Page number, at least 1. A blank value reads as 1.", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Rows per page, from 1 to 100. A blank value reads as the default.", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "A page of inventory in transit accounts with the list's status counts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryInTransitAccountsPage" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks the view permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountingSettingsProblem" } } } }, "422": { "description": "An invalid filter, search, sort, grouping or paging parameter: `error_code` is null and `errors` names it, `status.0` for the first status of a list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountingSettingsProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Accounting - Settings - Inventory In Transit Accounts" ], "summary": "Create a new inventory in transit account", "description": "An id already in use, by this company or another one, answers 409 inventory_in_transit_account_already_exists and changes nothing.", "operationId": "b745a2597d33cea5b18adaacd7adc3d5", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "id", "account_id", "center_id", "status", "type" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000" }, "account_id": { "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440001" }, "center_id": { "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440002" }, "status": { "type": "string", "example": "active", "enum": [ "active", "inactive" ] }, "type": { "type": "string", "example": "ASSET", "enum": [ "ASSET", "LIABILITY" ] } }, "type": "object" } } } }, "responses": { "201": { "description": "Inventory in transit account created successfully" }, "403": { "description": "The user lacks the create permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountingSettingsProblem" } } } }, "409": { "description": "The id is already in use, by this company or another one; nothing is written. `error_code` is inventory_in_transit_account_already_exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountingSettingsProblem" } } } }, "422": { "description": "Invalid fields, or an account or center that is not the company's, with `error_code` null and `errors` keyed by field; or a domain refusal placed on its field with its code: duplicate_active_inventory_in_transit_account on status when another active inventory in transit account of the company of its type exists, invalid_account_reference on account_id, invalid_center_reference on center_id. Nothing is written.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountingSettingsProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/accounting/settings/payable-accounts/{id}": { "get": { "tags": [ "Backoffice - Accounting - Settings - Payable Accountings" ], "summary": "Get a payable account of the company", "description": "Answers the list's row shape, with the code and name of the account and center, null when the reference does not resolve in the company. Another company's or an unknown id is 404. Requires `backoffice.accounting.settings.payable-accounts.view`.", "operationId": "380e633c97814a5fa6dd180e87cfff17", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The payable account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayableAccount" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks the view permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountingSettingsProblem" } } } }, "404": { "description": "The payable account is not one of the company's. `error_code` is payable_account_not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountingSettingsProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Backoffice - Accounting - Settings - Payable Accountings" ], "summary": "Update a payable account", "description": "The accounting account must not back any treasury account of the company, active or inactive (MER-4072), nor be configured as a receivable account of the company, default or not (MER-3668). Compatibility is checked only when the account changes: an existing association keeps saving while its account is unchanged, and none is removed automatically. An incompatible account answers 422 on accounting_account_payable_id (accounting_account_payable_backs_treasury_account or accounting_account_payable_configured_as_receivable).", "operationId": "ff5d4abe4cf09e0a3eeffc85bbdafa97", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "default", "accounting_account_payable_id", "accounting_center_payable_id" ], "properties": { "default": { "description": "Whether this is the company's default payable account. Send a JSON boolean; 1 and 0, as numbers or strings, are read as true and false.", "type": "boolean", "example": true }, "accounting_account_payable_id": { "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440001" }, "accounting_center_payable_id": { "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440002" } }, "type": "object" } } } }, "responses": { "200": { "description": "Payable account updated successfully" }, "403": { "description": "The user lacks the update permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountingSettingsProblem" } } } }, "404": { "description": "The payable account is not one of the company's. `error_code` is payable_account_not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountingSettingsProblem" } } } }, "422": { "description": "Invalid fields, or an accounting account or center that is not the company's, with `error_code` null and `errors` keyed by field; or a refusal of a changed accounting account placed on accounting_account_payable_id with its code: duplicate_accounting_account_payable when another payable account of the company already uses it, accounting_account_payable_backs_treasury_account, or accounting_account_payable_configured_as_receivable when a receivable account of the company (default or not) configures the account. Nothing is modified.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountingSettingsProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/accounting/settings/payable-accounts": { "get": { "tags": [ "Backoffice - Accounting - Settings - Payable Accountings" ], "summary": "Search the company's payable accounts", "description": "Lists the company's payable accounts with the code and name of each one's accounting account and center, null when the reference does not resolve in the company. `default` keeps the company's default account (`true` or `1`) or the others (`false` or `0`). `search` matches the account's or the center's code or name literally; it is trimmed and a blank term searches nothing. Without `sort_by` the order is the account's code ascending; a `sort_by` sent without `sort_order` reads descending, and a `sort_order` sent alone applies to the account's code. Ties are settled by id in the same direction. `group_by=default` lists the default account first, ahead of the requested order and before paging. `meta.counts` counts the matching accounts that are the default and the others under every filter but `default`, independent of the page, its size, the order and the grouping. A blank parameter is ignored; unknown parameters are dropped; any other invalid value is a 422 on its parameter. Requires `backoffice.accounting.settings.payable-accounts.view`; 403 precedes 422.", "operationId": "bc01567160d69cd66c6c11f179e759e6", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "default", "in": "query", "description": "`true` or `1` keeps the default account; `false` or `0` keeps the others.", "required": false, "schema": { "type": "string", "enum": [ "true", "false", "1", "0" ] } }, { "name": "search", "in": "query", "description": "Matches the account's or the center's code or name, literally; trimmed, and blank searches nothing.", "required": false, "schema": { "type": "string", "maxLength": 255 } }, { "name": "sort_by", "in": "query", "required": false, "schema": { "type": "string", "default": "account_code", "enum": [ "account_code", "created_at" ] } }, { "name": "sort_order", "in": "query", "description": "Ascending when `sort_by` is omitted; descending when `sort_by` is sent without it. Trimmed, any case.", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "group_by", "in": "query", "description": "`default` lists the default account first, before the requested order and before paging. `none` groups nothing.", "required": false, "schema": { "type": "string", "enum": [ "default", "none" ] } }, { "name": "page", "in": "query", "description": "Page number, at least 1. A blank value reads as 1.", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Rows per page, from 1 to 100. A blank value reads as the default.", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "A page of payable accounts with the list's default counts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayableAccountsPage" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks `backoffice.accounting.settings.payable-accounts.view`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountingSettingsProblem" } } } }, "422": { "description": "An invalid filter, search, sort, grouping or paging parameter: `error_code` is null and `errors` names it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountingSettingsProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Accounting - Settings - Payable Accountings" ], "summary": "Create a new payable account", "description": "The accounting account must not back any treasury account of the company, active or inactive (MER-4072), nor be configured as a receivable account of the company, default or not (MER-3668). An incompatible account answers 422 on accounting_account_payable_id (accounting_account_payable_backs_treasury_account or accounting_account_payable_configured_as_receivable) and nothing is created. An id already in use, by this company or another one, answers 409 payable_account_already_exists and changes nothing.", "operationId": "4928a3da591d6a1dba28b57649b261ee", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "id", "default", "accounting_account_payable_id", "accounting_center_payable_id" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000" }, "default": { "description": "Whether this is the company's default payable account. Send a JSON boolean; 1 and 0, as numbers or strings, are read as true and false.", "type": "boolean", "example": true }, "accounting_account_payable_id": { "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440001" }, "accounting_center_payable_id": { "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440002" } }, "type": "object" } } } }, "responses": { "201": { "description": "Payable account created successfully" }, "403": { "description": "The user lacks the create permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountingSettingsProblem" } } } }, "409": { "description": "The id is already in use, by this company or another one; nothing is written. `error_code` is payable_account_already_exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountingSettingsProblem" } } } }, "422": { "description": "Invalid fields, or an accounting account or center that is not the company's, with `error_code` null and `errors` keyed by field; or a refusal of the accounting account placed on accounting_account_payable_id with its code: duplicate_accounting_account_payable when another payable account of the company already uses it, accounting_account_payable_backs_treasury_account, or accounting_account_payable_configured_as_receivable when a receivable account of the company (default or not) configures the account. Nothing is created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountingSettingsProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/accounting/settings/posting-accounts/{id}": { "get": { "tags": [ "Backoffice - Accounting - Settings - Posting Accounts" ], "summary": "Get a posting account", "description": "Requires `backoffice.accounting.settings.posting-accounts.view`. A posting account of another company answers 404.", "operationId": "379095d3251852ec7f4fe72918bad906", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "The posting account id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The posting account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostingAccount" } } } }, "403": { "description": "The user lacks the view permission" }, "404": { "description": "The posting account does not exist in this company: posting_account_not_found", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "detail": { "type": "string", "example": "La cuenta de contabilización con ID 0199a3b2-6c1e-7f3a-9d2b-1a2b3c4d5e6f no existe" }, "error_code": { "type": "string", "example": "posting_account_not_found" } }, "type": "object" } } } }, "422": { "description": "The id is not a UUID" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Backoffice - Accounting - Settings - Posting Accounts" ], "summary": "Change the account, center or status of a posting account", "description": "The role is immutable and is not part of the body; a `role` sent anyway is ignored. To designate another role, register another posting account. A PUT that changes nothing answers 200 without writing. Reactivating a role that already has another active posting account answers 409 duplicate_active_posting_account. Requires `backoffice.accounting.settings.posting-accounts.update`.", "operationId": "9a237ddec856c99b84de906f92e38b41", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "The posting account id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "account_id", "center_id", "status" ], "properties": { "account_id": { "description": "A detail accounting account of this company, of a type the role accepts (not a group).", "type": "string", "format": "uuid", "example": "0199a3b2-0000-7000-8000-000000000001" }, "center_id": { "description": "An accounting center of this company.", "type": "string", "format": "uuid", "example": "0199a3b2-0000-7000-8000-000000000002" }, "status": { "type": "string", "example": "inactive", "enum": [ "active", "inactive" ] } }, "type": "object" } } } }, "responses": { "200": { "description": "Posting account updated, or already as requested" }, "403": { "description": "The user lacks the update permission" }, "404": { "description": "The posting account does not exist in this company: posting_account_not_found", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "detail": { "type": "string", "example": "La cuenta de contabilización con ID 0199a3b2-6c1e-7f3a-9d2b-1a2b3c4d5e6f no existe" }, "error_code": { "type": "string", "example": "posting_account_not_found" } }, "type": "object" } } } }, "409": { "description": "The role already has another active posting account: duplicate_active_posting_account", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "detail": { "type": "string", "example": "Ya existe una cuenta activa para el rol «Pérdida cambiaria realizada»" }, "error_code": { "type": "string", "example": "duplicate_active_posting_account" } }, "type": "object" } } } }, "422": { "description": "Validation error, a malformed id, or a domain rule rejected the change: posting_account_type_mismatch, invalid_account_reference, invalid_center_reference, invalid_posting_account_status, posting_account_on_group_account or posting_account_configured_as_receivable placed on account_id (`errors.account_id`) when the account is a group (even unchanged) or when the account changes to one a receivable account of the company (default or not) configures; an unchanged receivable account keeps saving. Nothing is modified.", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string", "example": "La cuenta del rol «Pérdida cambiaria realizada» debe ser de tipo Gasto" }, "error_code": { "type": "string", "example": "posting_account_type_mismatch", "nullable": true }, "errors": { "description": "Messages keyed by the field they refuse: set for a validation error and for posting_account_on_group_account and posting_account_configured_as_receivable, null for the other domain refusals.", "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Backoffice - Accounting - Settings - Posting Accounts" ], "summary": "Delete a posting account", "description": "Requires `backoffice.accounting.settings.posting-accounts.delete`.", "operationId": "b5c2cc4ab7f91761047014ac02a2c8fe", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "The posting account id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Posting account deleted" }, "403": { "description": "The user lacks the delete permission" }, "404": { "description": "The posting account does not exist in this company: posting_account_not_found", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "detail": { "type": "string", "example": "La cuenta de contabilización con ID 0199a3b2-6c1e-7f3a-9d2b-1a2b3c4d5e6f no existe" }, "error_code": { "type": "string", "example": "posting_account_not_found" } }, "type": "object" } } } }, "422": { "description": "The id is not a UUID" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/accounting/settings/posting-accounts": { "get": { "tags": [ "Backoffice - Accounting - Settings - Posting Accounts" ], "summary": "List the company's posting accounts by role", "description": "Lists the posting accounts ordered by role, active before inactive, then by creation and id. A company without posting accounts returns an empty `items` list with `total` 0. Each item carries the code and name of its account and center; they are null when the account or center does not resolve in the company. `status` takes one value or several (`status=active` or `status[]=active&status[]=inactive`), as alternatives; `all` or an empty value is ignored. `role` takes one role. `search` matches the account's or the center's code or name literally; it is trimmed and a blank term searches nothing. `meta.counts` counts the matching accounts by status under every filter but `status`, zero-filled and independent of the page and its size. A blank parameter is ignored; unknown parameters, `sort_by` and `group_by` included, are dropped; any other invalid value is a 422 on its parameter (`status.0` for the first status of a list). Requires `backoffice.accounting.settings.posting-accounts.view`; 403 precedes 422.", "operationId": "9f4165b8bbb3d3047b05754db6183062", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "role", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "realized_exchange_gain", "realized_exchange_loss", "unrealized_exchange_gain", "unrealized_exchange_loss", "bank_fees", "cash_shortage", "cash_overage", "sales_returns", "purchase_returns", "customer_advances", "supplier_advances", "vat_withholding_payable", "islr_withholding_payable", "igtf_payable", "vat_withholding_supported", "islr_withholding_supported", "reported_withholding_pending", "igtf_expense", "non_deductible_vat" ] } }, { "name": "status", "in": "query", "description": "One status, or `all` for every status. Same as one `status[]`.", "required": false, "schema": { "type": "string", "enum": [ "active", "inactive", "all" ] } }, { "name": "status[]", "in": "query", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "active", "inactive" ] } } }, { "name": "search", "in": "query", "description": "Matches the account's or the center's code or name, literally; trimmed, and blank searches nothing.", "required": false, "schema": { "type": "string", "maxLength": 255 } }, { "name": "page", "in": "query", "description": "Page number, at least 1. A blank value reads as 1.", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Rows per page, from 1 to 100. A blank value reads as the default.", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "A page of posting accounts with the list's status counts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostingAccountsPage" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks the view permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountingSettingsProblem" } } } }, "422": { "description": "An invalid filter, search or paging parameter: `error_code` is null and `errors` names it, `status.0` for the first status of a list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountingSettingsProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Accounting - Settings - Posting Accounts" ], "summary": "Designate the account and center of a role", "description": "Registers the account and center the company posts a role to. The account must be a detail account (no company-owned children); a group answers 422 posting_account_on_group_account on account_id. The realized and unrealized exchange gain and sales returns roles take a revenue account (type 4); the realized and unrealized exchange loss and bank fees roles an expense account (type 6); the purchase returns role a cost or an expense account (type 5 or 6); customer advances a liability account (type 2); supplier advances an asset account (type 1); the VAT withholding, ISLR withholding and IGTF payable roles a liability account (type 2); the VAT and ISLR withholding supported and the reported withholding pending roles an asset account (type 1); the IGTF expense role an expense account (type 6); the non-deductible VAT role, which a company that is not an ordinary VAT taxpayer debits its purchase VAT to (MER-5393), a cost or an expense account (type 5 or 6) of its own that no purchase line uses; another type answers 422 posting_account_type_mismatch. A role has at most one active posting account; a second active one answers 409 duplicate_active_posting_account and leaves the first unchanged. Inactive rows of a role are allowed. Requires `backoffice.accounting.settings.posting-accounts.create`.", "operationId": "88349bbc213e7a273b81f90ec680c9e9", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "id", "role", "account_id", "center_id", "status" ], "properties": { "id": { "description": "Client-generated UUID v7.", "type": "string", "format": "uuid", "example": "0199a3b2-6c1e-7f3a-9d2b-1a2b3c4d5e6f" }, "role": { "description": "Immutable once registered.", "type": "string", "example": "realized_exchange_gain", "enum": [ "realized_exchange_gain", "realized_exchange_loss", "unrealized_exchange_gain", "unrealized_exchange_loss", "bank_fees", "cash_shortage", "cash_overage", "sales_returns", "purchase_returns", "customer_advances", "supplier_advances", "vat_withholding_payable", "islr_withholding_payable", "igtf_payable", "vat_withholding_supported", "islr_withholding_supported", "reported_withholding_pending", "igtf_expense", "non_deductible_vat" ] }, "account_id": { "description": "A detail accounting account of this company (not a group).", "type": "string", "format": "uuid", "example": "0199a3b2-0000-7000-8000-000000000001" }, "center_id": { "description": "An accounting center of this company.", "type": "string", "format": "uuid", "example": "0199a3b2-0000-7000-8000-000000000002" }, "status": { "type": "string", "example": "active", "enum": [ "active", "inactive" ] } }, "type": "object" } } } }, "responses": { "201": { "description": "Posting account registered" }, "403": { "description": "The user lacks the create permission" }, "409": { "description": "The id already exists or the role already has an active posting account: posting_account_already_exists, duplicate_active_posting_account", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "detail": { "type": "string", "example": "Ya existe una cuenta activa para el rol «Ganancia cambiaria realizada»" }, "error_code": { "type": "string", "example": "duplicate_active_posting_account" } }, "type": "object" } } } }, "422": { "description": "Validation error, or a domain rule rejected the posting account: posting_account_type_mismatch, invalid_account_reference, invalid_center_reference, invalid_posting_account_role, invalid_posting_account_status, posting_account_on_group_account or posting_account_configured_as_receivable placed on account_id (`errors.account_id`) when the account is a group or when an asset role names an account a receivable account of the company (default or not) configures. Nothing is written.", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string", "example": "La cuenta del rol «Ganancia cambiaria realizada» debe ser de tipo Ingreso" }, "error_code": { "type": "string", "example": "posting_account_type_mismatch", "nullable": true }, "errors": { "description": "Messages keyed by the field they refuse: set for a validation error and for posting_account_on_group_account and posting_account_configured_as_receivable, null for the other domain refusals.", "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/accounting/settings/receivable-accounts/{id}": { "get": { "tags": [ "Backoffice - Accounting - Settings - Receivable Accountings" ], "summary": "Get a receivable account of the company", "description": "Answers the list's row shape, with the code and name of the account and center, null when the reference does not resolve in the company. Another company's or an unknown id is 404. Requires `backoffice.accounting.settings.receivable-accounts.view`.", "operationId": "c27cc00bf4595bcd251c6a63bd4a09a3", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The receivable account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReceivableAccount" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks the view permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountingSettingsProblem" } } } }, "404": { "description": "The receivable account is not one of the company's. `error_code` is receivable_account_not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountingSettingsProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Backoffice - Receivable Accounts" ], "summary": "Update a receivable account", "description": "The accounting account must be an asset (type 1) of the company, and no designation in the company's accounting settings may reserve it to another role, whatever that designation's status: the company's VAT input account, the accounting account of any tax, or the account of any posting account role. It must also not back any treasury account of the company, active or inactive (MER-4072). Accounts are never classified by name or code; inventory-in-transit accounts are not checked. It must also not be configured as a payable account of the company, default or not (MER-3668). The reciprocal rule guards the other writers: the VAT input account, tax and posting account writes reject an account already configured as receivable (MER-3906). The account is checked only when it changes: an existing association keeps saving while its account is unchanged, and none is removed automatically. An incompatible account answers 422 and nothing is modified.", "operationId": "15386f35bdbe1258c94ca6cb22806291", "parameters": [ { "name": "tenant", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "Receivable Account ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "default", "accounting_account_receivable_id", "accounting_center_receivable_id" ], "properties": { "default": { "description": "Whether this is the company's default receivable account. Send a JSON boolean; 1 and 0, as numbers or strings, are read as true and false.", "type": "boolean", "example": false }, "accounting_account_receivable_id": { "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440001" }, "accounting_center_receivable_id": { "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440002" } }, "type": "object" } } } }, "responses": { "200": { "description": "Receivable account updated successfully" }, "403": { "description": "The user lacks the update permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountingSettingsProblem" } } } }, "404": { "description": "The receivable account is not one of the company's. `error_code` is receivable_account_not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountingSettingsProblem" } } } }, "422": { "description": "Invalid fields, or an accounting account or center that is not the company's, with `error_code` null and `errors` keyed by field; or a refusal of a changed accounting account placed on accounting_account_receivable_id with its code: duplicate_accounting_account_receivable when another receivable account of the company already uses it, accounting_account_receivable_not_an_asset, accounting_account_receivable_reserved_by_role, accounting_account_receivable_backs_treasury_account, or accounting_account_receivable_configured_as_payable when a payable account of the company (default or not) configures the account. The message names the account and, for a reservation, every role that holds it. Nothing is modified.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountingSettingsProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Backoffice - Accounting - Settings - Receivable Accountings" ], "summary": "Delete a receivable account", "operationId": "7b79aa5ba3091860658ed22ef3d6dfba", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Receivable account deleted successfully" }, "403": { "description": "Unauthorized" }, "404": { "description": "Receivable account not found" }, "409": { "description": "The account is the company default (`receivable_account_is_default`) or a sales invoice, order, quote or contract references its chart account (`receivable_account_in_use`); deactivate or reassign instead", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "detail": { "type": "string", "example": "La cuenta por cobrar <123e4567-e89b-12d3-a456-426655440000> está en uso en documentos y no se puede eliminar; desactívala en su lugar" }, "error_code": { "type": "string", "example": "receivable_account_in_use" } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/accounting/settings/receivable-accounts": { "get": { "tags": [ "Backoffice - Receivable Accounts" ], "summary": "Search the company's receivable accounts", "description": "Lists the company's receivable accounts with the code and name of each one's accounting account and center, null when the reference does not resolve in the company. `default` keeps the company's default account (`true` or `1`) or the others (`false` or `0`). `search` matches the account's or the center's code or name literally; it is trimmed and a blank term searches nothing. Without `sort_by` the order is the account's code ascending; a `sort_by` sent without `sort_order` reads descending, and a `sort_order` sent alone applies to the account's code. Ties are settled by id in the same direction. `group_by=default` lists the default account first, ahead of the requested order and before paging. `meta.counts` counts the matching accounts that are the default and the others under every filter but `default`, independent of the page, its size, the order and the grouping. A blank parameter is ignored; unknown parameters are dropped; any other invalid value is a 422 on its parameter. Requires `backoffice.accounting.settings.receivable-accounts.view`; 403 precedes 422.", "operationId": "326f14fce0f3ef72b9ca1c4c3f89fe4f", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "default", "in": "query", "description": "`true` or `1` keeps the default account; `false` or `0` keeps the others.", "required": false, "schema": { "type": "string", "enum": [ "true", "false", "1", "0" ] } }, { "name": "search", "in": "query", "description": "Matches the account's or the center's code or name, literally; trimmed, and blank searches nothing.", "required": false, "schema": { "type": "string", "maxLength": 255 } }, { "name": "sort_by", "in": "query", "required": false, "schema": { "type": "string", "default": "account_code", "enum": [ "account_code", "created_at" ] } }, { "name": "sort_order", "in": "query", "description": "Ascending when `sort_by` is omitted; descending when `sort_by` is sent without it. Trimmed, any case.", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "group_by", "in": "query", "description": "`default` lists the default account first, before the requested order and before paging. `none` groups nothing.", "required": false, "schema": { "type": "string", "enum": [ "default", "none" ] } }, { "name": "page", "in": "query", "description": "Page number, at least 1. A blank value reads as 1.", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Rows per page, from 1 to 100. A blank value reads as the default.", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "A page of receivable accounts with the list's default counts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReceivableAccountsPage" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks the view permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountingSettingsProblem" } } } }, "422": { "description": "An invalid filter, search, sort, grouping or paging parameter: `error_code` is null and `errors` names it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountingSettingsProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Receivable Accounts" ], "summary": "Create a new receivable account", "description": "The accounting account must be an asset (type 1) of the company, and no designation in the company's accounting settings may reserve it to another role, whatever that designation's status: the company's VAT input account, the accounting account of any tax, or the account of any posting account role. It must also not back any treasury account of the company, active or inactive (MER-4072). Accounts are never classified by name or code; inventory-in-transit accounts are not checked. It must also not be configured as a payable account of the company, default or not (MER-3668). The reciprocal rule guards the other writers: the VAT input account, tax and posting account writes reject an account already configured as receivable (MER-3906). An incompatible account answers 422 and nothing is created. An id already in use, by this company or another one, answers 409 receivable_account_already_exists and changes nothing.", "operationId": "844a6e6aabe3e497f5de5ecbfcd6e8e9", "parameters": [ { "name": "tenant", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "id", "default", "accounting_account_receivable_id", "accounting_center_receivable_id" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000" }, "default": { "description": "Whether this is the company's default receivable account. Send a JSON boolean; 1 and 0, as numbers or strings, are read as true and false.", "type": "boolean", "example": false }, "accounting_account_receivable_id": { "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440001" }, "accounting_center_receivable_id": { "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440002" } }, "type": "object" } } } }, "responses": { "201": { "description": "Receivable account created successfully" }, "403": { "description": "The user lacks the create permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountingSettingsProblem" } } } }, "409": { "description": "The id is already in use, by this company or another one; nothing is written. `error_code` is receivable_account_already_exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountingSettingsProblem" } } } }, "422": { "description": "Invalid fields, or an accounting account or center that is not the company's, with `error_code` null and `errors` keyed by field; or a refusal of the accounting account placed on accounting_account_receivable_id with its code: duplicate_accounting_account_receivable when another receivable account of the company already uses it, accounting_account_receivable_not_an_asset, accounting_account_receivable_reserved_by_role, accounting_account_receivable_backs_treasury_account, or accounting_account_receivable_configured_as_payable when a payable account of the company (default or not) configures the account. The message names the account and, for a reservation, every role that holds it. Nothing is created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountingSettingsProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/accounting/settings/taxes/{id}": { "get": { "tags": [ "Backoffice - Accounting - Settings - Taxes" ], "summary": "Get a tax of the company", "description": "Answers the list's row shape, with the code and name of the tax's accounting account and center, null when the reference does not resolve in the company. Another company's or an unknown id is 404. Requires `backoffice.accounting.settings.taxes.view`.", "operationId": "9e99887fc522c0b452e1ab13624cdbdd", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "The ID of the tax to retrieve", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The tax", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tax" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks the view permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountingSettingsProblem" } } } }, "404": { "description": "The tax is not one of the company's. `error_code` is tax_not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountingSettingsProblem" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Internal Server Error" }, "status": { "type": "integer", "example": 500 }, "detail": { "type": "string", "example": "An unexpected error occurred while processing your request." } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Backoffice - Accounting - Settings - Taxes" ], "summary": "Update an existing tax", "description": "Updates a tax of the company. The accounting account cannot change, and the rate cannot change once a document line cites the tax; the name and the other fields still can. The receivable rule of creation never answers here: the account cannot change (tax_accounting_account_cannot_change), and a tax saved earlier on an account configured as receivable keeps saving its other fields.", "operationId": "f8abe85f5c70f87cb2d8f5c2b19ce11e", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "The ID of the tax to update", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "rate", "accounting_account_id" ], "properties": { "is_default_purchase": { "type": "boolean" }, "is_default_sales": { "type": "boolean" }, "name": { "type": "string", "example": "VAT", "maxLength": 100, "minLength": 3 }, "description": { "type": "string", "example": "Value Added Tax", "nullable": true, "maxLength": 255 }, "rate": { "type": "string", "pattern": "^(?:0*(?:[0-9]|[1-9][0-9])(?:\\.[0-9]{1,2})?|0*100(?:\\.0{1,2})?)$", "example": "16.00" }, "kind": { "description": "Optional fiscal category; omit to keep the existing kind", "type": "string", "example": "vat_general", "enum": [ "vat_general", "vat_reduced", "vat_additional", "exempt", "exonerated", "not_subject", "export", "other" ] }, "accounting_account_id": { "description": "The ID of the accounting account associated with this tax", "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426655440000" }, "status": { "type": "string", "example": "active", "enum": [ "active", "inactive" ] } }, "type": "object" } } } }, "responses": { "200": { "description": "Tax updated successfully" }, "403": { "description": "The user lacks the update permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountingSettingsProblem" } } } }, "404": { "description": "The tax is not one of the company's. `error_code` is tax_not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountingSettingsProblem" } } } }, "422": { "description": "Invalid fields, with `error_code` null and `errors` keyed by field; or a domain refusal placed on its field with its code: tax_rate_immutable_after_document_reference and invalid_tax_rate on rate, tax_kind_rate_mismatch and invalid_tax_kind on kind, tax_accounting_account_cannot_change on accounting_account_id. Nothing is written.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountingSettingsProblem" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Internal Server Error" }, "status": { "type": "integer", "example": 500 }, "detail": { "type": "string", "example": "An unexpected error occurred while processing your request." } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/accounting/settings/taxes": { "get": { "tags": [ "Backoffice - Accounting - Settings - Taxes" ], "summary": "Search the company's taxes", "description": "Lists the company's taxes with the code and name of each one's accounting account and center, null when the reference does not resolve in the company. `status` and `kind` take one value or several (`status=active` or `status[]=active&status[]=inactive`): values are alternatives within a field and both fields must match; `all` or an empty value is ignored. `search` matches the name or the description literally; it is trimmed and a blank term searches nothing. Without `sort_by` the order is the name ascending; a `sort_by` sent without `sort_order` reads descending, and a `sort_order` sent alone applies to the name. Ties are settled by id in the same direction. `group_by=status` lists active taxes before inactive ones, ahead of the requested order and before paging. `meta.counts` counts the matching taxes by status under every filter but `status`, zero-filled and independent of the page, its size, the order and the grouping. A blank parameter is ignored; unknown parameters are dropped; any other invalid value is a 422 on its parameter (`status.0` for the first status of a list). Requires `backoffice.accounting.settings.taxes.view`; 403 precedes 422.", "operationId": "e824c167577883ed9f09156eb0923cb5", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "search", "in": "query", "description": "Matches the name or the description, literally; trimmed, and blank searches nothing.", "required": false, "schema": { "type": "string", "maxLength": 255 } }, { "name": "status", "in": "query", "description": "One status, or `all` for every status. Same as one `status[]`.", "required": false, "schema": { "type": "string", "enum": [ "active", "inactive", "all" ] } }, { "name": "status[]", "in": "query", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "active", "inactive" ] } } }, { "name": "kind", "in": "query", "description": "One fiscal kind, or `all` for every kind. Same as one `kind[]`.", "required": false, "schema": { "type": "string", "enum": [ "vat_general", "vat_reduced", "vat_additional", "exempt", "exonerated", "not_subject", "export", "other", "all" ] } }, { "name": "kind[]", "in": "query", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "vat_general", "vat_reduced", "vat_additional", "exempt", "exonerated", "not_subject", "export", "other" ] } } }, { "name": "sort_by", "in": "query", "required": false, "schema": { "type": "string", "default": "name", "enum": [ "name", "rate", "created_at" ] } }, { "name": "sort_order", "in": "query", "description": "Ascending when `sort_by` is omitted; descending when `sort_by` is sent without it. Trimmed, any case.", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "group_by", "in": "query", "description": "`status` lists active taxes first, before the requested order and before paging. `none` groups nothing.", "required": false, "schema": { "type": "string", "enum": [ "status", "none" ] } }, { "name": "page", "in": "query", "description": "Page number, at least 1. A blank value reads as 1.", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Rows per page, from 1 to 100. A blank value reads as the default.", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "A page of taxes with the list's status counts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxesPage" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks `backoffice.accounting.settings.taxes.view`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountingSettingsProblem" } } } }, "422": { "description": "An invalid filter, search, sort, grouping or paging parameter: `error_code` is null and `errors` names it, `status.0` for the first status of a list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountingSettingsProblem" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Internal Server Error" }, "status": { "type": "integer", "example": 500 }, "detail": { "type": "string", "example": "An unexpected error occurred while processing your request." } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Accounting - Settings - Taxes" ], "summary": "Create a new tax", "description": "Creates an active tax under the client-generated id. An id already in use, by this company or another one, answers 409 tax_already_exists and changes nothing.", "operationId": "a353f00a799106f9c71a23ebf2b1861e", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "id", "name", "rate", "accounting_account_id" ], "properties": { "is_default_purchase": { "type": "boolean" }, "is_default_sales": { "type": "boolean" }, "id": { "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426655440000" }, "name": { "type": "string", "example": "VAT", "maxLength": 100, "minLength": 3 }, "description": { "type": "string", "example": "Value Added Tax", "nullable": true, "maxLength": 255 }, "rate": { "type": "string", "pattern": "^(?:0*(?:[0-9]|[1-9][0-9])(?:\\.[0-9]{1,2})?|0*100(?:\\.0{1,2})?)$", "example": "16.00" }, "kind": { "description": "Optional fiscal category; defaults to other when omitted", "type": "string", "example": "vat_general", "enum": [ "vat_general", "vat_reduced", "vat_additional", "exempt", "exonerated", "not_subject", "export", "other" ] }, "accounting_account_id": { "description": "The ID of the accounting account associated with this tax", "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426655440000" }, "accounting_center_id": { "description": "Optional accounting center for this tax; defaults to the company's default center when omitted", "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426655440000", "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Tax created successfully" }, "403": { "description": "The user lacks the create permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountingSettingsProblem" } } } }, "409": { "description": "The id is already in use, by this company or another one; nothing is written. `error_code` is tax_already_exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountingSettingsProblem" } } } }, "422": { "description": "Invalid fields, with `error_code` null and `errors` keyed by field; or a domain refusal placed on its field with its code: invalid_tax_rate on rate, invalid_tax_kind and tax_kind_rate_mismatch on kind, tax_default_accounting_center_not_found on accounting_center_id, tax_accounting_account_configured_as_receivable on accounting_account_id when a receivable account of the company (default or not) configures the account. Nothing is written.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountingSettingsProblem" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Internal Server Error" }, "status": { "type": "integer", "example": 500 }, "detail": { "type": "string", "example": "An unexpected error occurred while processing your request." } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/accounting/settings/vat-input-accounts/{id}": { "get": { "tags": [ "Backoffice - Accounting - Settings - Vat Input Accounts" ], "summary": "Get a VAT input (IVA crédito fiscal) account of the company", "description": "Answers the list's row shape, with the code and name of the account and center, null when the reference does not resolve in the company, and its non-blocking `warnings` (MER-5393): VAT_INPUT_ACCOUNT_NOT_AN_ASSET when its account is not an asset, as a designation saved before the write-time refusal may be. Another company's or an unknown id is 404. Requires `backoffice.accounting.settings.vat-input-accounts.view`.", "operationId": "6f357083278e4935c4943e2c103a1689", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The VAT input account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VatInputAccount" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks the view permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountingSettingsProblem" } } } }, "404": { "description": "The account is not one of the company's. `error_code` is vat_input_account_not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountingSettingsProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Backoffice - Accounting - Settings - Vat Input Accounts" ], "summary": "Update an IVA crédito fiscal account", "description": "A second active VAT input account of the company answers 409 duplicate_active_vat_input_account on status and leaves the row unchanged. Requires `backoffice.accounting.settings.vat-input-accounts.update`.", "operationId": "5e5ece4ddaaf49213f7501ac15993b29", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "account_id", "center_id", "status" ], "properties": { "account_id": { "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440001" }, "center_id": { "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440002" }, "status": { "type": "string", "example": "active", "enum": [ "active", "inactive" ] } }, "type": "object" } } } }, "responses": { "200": { "description": "VAT input account updated successfully" }, "403": { "description": "The user lacks the update permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountingSettingsProblem" } } } }, "404": { "description": "The VAT input account is not one of the company's. `error_code` is vat_input_account_not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountingSettingsProblem" } } } }, "409": { "description": "Another active VAT input account of the company exists (`duplicate_active_vat_input_account` on `errors.status`). Nothing is modified.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountingSettingsProblem" } } } }, "422": { "description": "Invalid fields, or an account or center that is not the company's, with `error_code` null and `errors` keyed by field; or a domain refusal placed on its field with its code: invalid_account_reference on account_id, invalid_center_reference on center_id, vat_input_account_not_an_asset on account_id when the account changes to one that is not an asset (type 1), since the fiscal credit is a right to deduct (MER-5393), vat_input_account_configured_as_receivable on account_id when the account changes to one a receivable account of the company (default or not) configures; an unchanged account keeps saving, and its reads carry the VAT_INPUT_ACCOUNT_NOT_AN_ASSET warning. Nothing is modified.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountingSettingsProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Backoffice - Accounting - Settings - Vat Input Accounts" ], "summary": "Delete an IVA crédito fiscal account", "description": "Requires `backoffice.accounting.settings.vat-input-accounts.delete`. Another company's or an unknown id is 404.", "operationId": "3f3d1a198ecfdbcf6f13a7833c2b4ea1", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "VAT input account deleted successfully" }, "403": { "description": "The user lacks the delete permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountingSettingsProblem" } } } }, "404": { "description": "The VAT input account is not one of the company's. `error_code` is vat_input_account_not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountingSettingsProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/accounting/settings/vat-input-accounts": { "get": { "tags": [ "Backoffice - Accounting - Settings - Vat Input Accounts" ], "summary": "Search the company's VAT input (IVA crédito fiscal) accounts", "description": "Lists the company's VAT input accounts with the code and name of each one's accounting account and center, null when the reference does not resolve in the company. Each row carries its non-blocking `warnings` (MER-5393): VAT_INPUT_ACCOUNT_NOT_AN_ASSET when its account is not an asset, as a designation saved before the write-time refusal may be; `[]` otherwise. `status` takes one value or several (`status=active` or `status[]=active&status[]=inactive`), as alternatives; `all` or an empty value is ignored. A company holds one active account at most. `search` matches the account's or the center's code or name literally, never the status text; it is trimmed and a blank term searches nothing. Without `sort_by` the order is the account's code ascending; a `sort_by` sent without `sort_order` reads descending, and a `sort_order` sent alone applies to the account's code. Ties are settled by id in the same direction. `group_by=status` lists active accounts before inactive ones, ahead of the requested order and before paging. `meta.counts` counts the matching accounts by status under every filter but `status`, zero-filled and independent of the page, its size, the order and the grouping. A blank parameter is ignored; unknown parameters are dropped; any other invalid value is a 422 on its parameter (`status.0` for the first status of a list). Requires `backoffice.accounting.settings.vat-input-accounts.view`; 403 precedes 422.", "operationId": "a909864d338cdcf4561854743d2a97d1", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "description": "One status, or `all` for every status. Same as one `status[]`.", "required": false, "schema": { "type": "string", "enum": [ "active", "inactive", "all" ] } }, { "name": "status[]", "in": "query", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "active", "inactive" ] } } }, { "name": "search", "in": "query", "description": "Matches the account's or the center's code or name, literally; trimmed, and blank searches nothing.", "required": false, "schema": { "type": "string", "maxLength": 255 } }, { "name": "sort_by", "in": "query", "required": false, "schema": { "type": "string", "default": "account_code", "enum": [ "account_code", "created_at" ] } }, { "name": "sort_order", "in": "query", "description": "Ascending when `sort_by` is omitted; descending when `sort_by` is sent without it. Trimmed, any case.", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "group_by", "in": "query", "description": "`status` lists active accounts first, before the requested order and before paging. `none` groups nothing.", "required": false, "schema": { "type": "string", "enum": [ "status", "none" ] } }, { "name": "page", "in": "query", "description": "Page number, at least 1. A blank value reads as 1.", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Rows per page, from 1 to 100. A blank value reads as the default.", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "A page of VAT input accounts with the list's status counts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VatInputAccountsPage" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks the view permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountingSettingsProblem" } } } }, "422": { "description": "An invalid filter, search, sort, grouping or paging parameter: `error_code` is null and `errors` names it, `status.0` for the first status of a list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountingSettingsProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Accounting - Settings - Vat Input Accounts" ], "summary": "Create a new IVA crédito fiscal account", "description": "An id already in use, by this company or another one, answers 409 vat_input_account_already_exists and changes nothing. A second active VAT input account of the company answers 409 duplicate_active_vat_input_account on status and leaves the first unchanged. Requires `backoffice.accounting.settings.vat-input-accounts.create`.", "operationId": "a34cab0b24e9f59deb39b4c3deb6c0a1", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "id", "account_id", "center_id", "status" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000" }, "account_id": { "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440001" }, "center_id": { "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440002" }, "status": { "type": "string", "example": "active", "enum": [ "active", "inactive" ] } }, "type": "object" } } } }, "responses": { "201": { "description": "VAT input account created successfully" }, "403": { "description": "The user lacks the create permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountingSettingsProblem" } } } }, "409": { "description": "The id is already in use (`vat_input_account_already_exists`), or another active VAT input account of the company exists (`duplicate_active_vat_input_account` on `errors.status`). Nothing is written.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountingSettingsProblem" } } } }, "422": { "description": "Invalid fields, or an account or center that is not the company's, with `error_code` null and `errors` keyed by field; or a domain refusal placed on its field with its code: invalid_account_reference on account_id, invalid_center_reference on center_id, vat_input_account_not_an_asset on account_id when the account is not an asset (type 1), since the fiscal credit is a right to deduct (MER-5393), vat_input_account_configured_as_receivable on account_id when a receivable account of the company (default or not) configures the account. Nothing is written.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountingSettingsProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/accounting/taxes/lookup": { "get": { "tags": [ "Backoffice - Accounting - Tax Lookups" ], "summary": "Lookup taxes for cross-module forms (tenant membership only — no taxes.view required)", "operationId": "b05e46f1937bb7cdce1736fd501baf2e", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "active", "inactive" ] } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 200, "minimum": 1 } } ], "responses": { "200": { "description": "Paginated list of taxes — minimal projection for dropdowns", "content": { "application/json": { "schema": { "properties": { "items": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "example": "IVA" }, "rate": { "type": "string", "example": "16.00" }, "kind": { "type": "string", "example": "vat_general", "enum": [ "vat_general", "vat_reduced", "vat_additional", "exempt", "exonerated", "not_subject", "export", "other" ] }, "is_default_purchase": { "type": "boolean" }, "is_default_sales": { "type": "boolean" }, "status": { "type": "string", "enum": [ "active", "inactive" ] } }, "type": "object" } }, "total": { "type": "integer" }, "per_page": { "type": "integer" }, "current_page": { "type": "integer" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Authenticated but not a member of this tenant" }, "404": { "description": "Tenant does not exist (indistinguishable from missing route)" }, "422": { "description": "Invalid status filter" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/accounting/transactions": { "get": { "tags": [ "Accounting Transactions" ], "summary": "Get accounting transactions", "description": "Retrieve a paginated list of accounting transactions with accounting details. Readable unscoped with any of backoffice.purchases.purchases-invoices.view, backoffice.purchases.payments.view, backoffice.sales.sales-invoices.view, backoffice.inventory.adjustments.view or backoffice.inventory.transformations.view. Each of these reads one document only, and only when its linkable_type and a non-empty linkable_id are sent: backoffice.inventory.entries.view with linkable_type=inventory_entry, backoffice.inventory.dispatches.view with linkable_type=inventory_dispatch, backoffice.treasury.treasury-transfers.view with linkable_type=treasury_transfer, backoffice.accounting.manual-entries.view with linkable_type=manual_entry, backoffice.purchases.credit-notes.view with linkable_type=purchase_credit_note, backoffice.purchases.debit-notes.view with linkable_type=purchase_debit_note, and collections.view with linkable_type=sales_collection.", "operationId": "getAccountingTransactions", "parameters": [ { "name": "tenant", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "linkable_id", "in": "query", "description": "Filter by the linked document id (e.g. purchase invoice, supplier credit or debit note, treasury transfer or manual entry)", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "linkable_type", "in": "query", "description": "Filter by linkable type: purchase_invoice, purchase_payment, purchase_credit_note, purchase_debit_note, sales_invoice, sales_collection, sales_credit_note, sales_debit_note, inventory_adjustment, inventory_entry, inventory_transformation, inventory_dispatch, opening_balance, treasury_transfer or manual_entry", "required": false, "schema": { "type": "string" } }, { "name": "with_source_applications", "in": "query", "description": "When true with linkable_type sales_collection or purchase_payment and a non-empty linkable_id, also include journals linked to credit applications whose source is that advance (live and reverted). With any other or missing linkable the flag is ignored. Absent keeps current behavior. Send a JSON boolean; 1 and 0, as numbers or strings, are read as true and false.", "required": false, "schema": { "type": "boolean" } }, { "name": "type", "in": "query", "description": "Filter by transaction type", "required": false, "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Items per page", "required": false, "schema": { "type": "integer", "default": 15, "maximum": 100, "minimum": 1 } }, { "name": "sort_by", "in": "query", "description": "Any column of backoffice__accounting__transactions, bare or prefixed with the table name and a dot. Without it the list orders by code descending. An empty value counts as absent. Any other value answers 422 invalid_list_sort.", "required": false, "schema": { "type": "string" } }, { "name": "sort_order", "in": "query", "description": "Checked even without sort_by, but it only orders a sort_by that is sent; a sort_by without it reads descending. Read ignoring case and surrounding spaces. An empty value counts as absent. Any other value answers 422 invalid_list_sort.", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Transactions retrieved successfully", "content": { "application/json": { "schema": { "properties": { "items": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "type": { "type": "string" }, "linkable_id": { "type": "string", "format": "uuid" }, "linkable_type": { "type": "string" }, "reverses_transaction_id": { "type": "string", "format": "uuid", "nullable": true }, "reversed_by_transaction_id": { "type": "string", "format": "uuid", "nullable": true }, "date": { "type": "string", "format": "date" }, "created_at": { "type": "string", "example": "2026-01-15 12:34:56" }, "company_id": { "type": "string", "format": "uuid" }, "items": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "accounting_account_id": { "type": "string", "format": "uuid" }, "accounting_account_code": { "type": "string" }, "accounting_account_name": { "type": "string" }, "accounting_center_id": { "type": "string", "format": "uuid" }, "accounting_center_code": { "type": "string" }, "accounting_center_name": { "type": "string" }, "debit": { "type": "string", "example": "1000.00" }, "credit": { "type": "string", "example": "0.00" }, "date": { "type": "string", "format": "date" }, "origin_type": { "type": "string" }, "origin_id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "original_currency": { "type": "string", "example": "USD", "nullable": true }, "original_amount": { "type": "string", "example": "100.00", "nullable": true }, "reporting_debit": { "type": "string", "example": "100.00", "nullable": true }, "reporting_credit": { "type": "string", "example": "0.00", "nullable": true }, "functional_rate": { "type": "string", "example": "1.00000000", "nullable": true }, "reporting_rate": { "type": "string", "example": "1.00000000", "nullable": true } }, "type": "object" } } }, "type": "object" } }, "total": { "type": "integer" }, "per_page": { "type": "integer" }, "current_page": { "type": "integer" } }, "type": "object" } } } }, "403": { "description": "The caller holds none of the admitting view permissions, or holds only document-scoped view permissions (inventory entries, inventory dispatches, treasury-transfers, manual-entries, purchases credit-notes or debit-notes, sales collections) without that permission's linkable_type and a non-empty linkable_id." }, "422": { "description": "invalid_list_sort: an unknown sort_by or a sort_order other than asc/desc; errors names the parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidListSortProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/fiscal/tax-declarations/{documentId}/attachments/{attachmentId}": { "delete": { "tags": [ "Backoffice - Fiscal - Tax Declarations" ], "summary": "Delete a file attached to a tax declaration", "description": "Requires backoffice.fiscal.declarations.manage. Soft-deletes the attachment metadata.", "operationId": "40c64948aa14c0a23ea508b9d5805341", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "documentId", "in": "path", "description": "The tax declaration id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "attachmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Attachment deleted" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Missing backoffice.fiscal.declarations.manage" }, "404": { "description": "Tax declaration or attachment not found" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/treasury/bank-reconciliations/{documentId}/attachments/{attachmentId}": { "delete": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "Delete evidence of a month's bank reconciliation", "description": "Requires backoffice.treasury.bank-reconciliations.view and company membership. The reconciliation month and the evidence ids must belong to the route company and parent; another company's month reads as absent. Authors/uploaders or company administrators delete their evidence. A missing statement never keeps a month from closing.", "operationId": "2c4a4ec9a987f4c6f094bb0faa0a8923", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "documentId", "in": "path", "description": "The month's bank reconciliation row (`reconciliation.id`)", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "attachmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Evidence deleted" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankStatementMessageError" } } } }, "403": { "description": "Missing backoffice.treasury.bank-reconciliations.view or company membership; actor cannot delete another user's evidence", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/BankStatementProblem" }, { "$ref": "#/components/schemas/BankStatementMiddlewareProblem" } ] } } } }, "404": { "description": "Reconciliation month or attachment not found; foreign parents and substituted evidence ids are hidden", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/BankStatementProblem" }, { "$ref": "#/components/schemas/BankStatementMessageError" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/orders/{documentId}/attachments/{attachmentId}": { "delete": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "Soft-delete an attachment on a purchase order (Pedido)", "description": "Soft-deletes the attachment metadata. The blob is retained. Author or company admin (AuthorizationPolicy::isAdmin) may delete.", "operationId": "7876ba8f51e7f7b512adbc18ab284978", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "attachmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Attachment soft-deleted" }, "403": { "description": "Actor is not the uploader and is not an admin", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Forbidden" }, "status": { "type": "integer", "example": 403 }, "error_code": { "type": "string", "example": "attachment_deletion_not_allowed" } }, "type": "object" } } } }, "404": { "description": "Document or attachment not found", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "error_code": { "type": "string", "example": "attachment_not_found" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/purchases-orders/{documentId}/attachments/{attachmentId}": { "delete": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "Soft-delete an attachment on a purchase order (Orden de compra)", "description": "Soft-deletes the attachment metadata. The blob is retained. Author or company admin (AuthorizationPolicy::isAdmin) may delete.", "operationId": "0ee58c868c1733a8bcea3670f06d439b", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "attachmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Attachment soft-deleted" }, "403": { "description": "Actor is not the uploader and is not an admin", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Forbidden" }, "status": { "type": "integer", "example": 403 }, "error_code": { "type": "string", "example": "attachment_deletion_not_allowed" } }, "type": "object" } } } }, "404": { "description": "Document or attachment not found", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "error_code": { "type": "string", "example": "attachment_not_found" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/providers/{documentId}/attachments/{attachmentId}": { "delete": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "Soft-delete an attachment on a provider", "description": "Requires `backoffice.purchases.providers.view`. Soft-deletes the attachment metadata. The blob is retained. Author or company admin (AuthorizationPolicy::isAdmin) may delete.", "operationId": "b7692822d5d7336a88a8d47f7204b649", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "attachmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Attachment soft-deleted" }, "403": { "description": "Actor is not the uploader and is not an admin", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Forbidden" }, "status": { "type": "integer", "example": 403 }, "error_code": { "type": "string", "example": "attachment_deletion_not_allowed" } }, "type": "object" } } } }, "404": { "description": "Document or attachment not found", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "error_code": { "type": "string", "example": "attachment_not_found" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/collections/{documentId}/attachments/{attachmentId}": { "delete": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "Delete collection evidence", "description": "Requires collections.view and company membership. The parent Collection and evidence ids must belong to the route company and parent. Comments are plain text. Authors alone edit comments; authors/uploaders or company administrators delete their evidence. A screenshot reports payment evidence and never sets or confirms the informational crediting date.", "operationId": "634bf83b5fa1544ade0b5ee175f2e2ba", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "attachmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Delete collection evidence" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "oneOf": [ { "required": [ "message" ], "properties": { "message": { "type": "string" } }, "type": "object" } ] } } } }, "403": { "description": "Missing collections.view or company membership; actor cannot edit/delete another user evidence or attach to another user comment", "content": { "application/json": { "schema": { "oneOf": [ { "required": [ "message" ], "properties": { "message": { "type": "string" } }, "type": "object" }, { "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "error_code": { "type": "string", "nullable": true }, "errors": { "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" } ] } } } }, "404": { "description": "Collection, scoped comment or attachment not found; foreign parents and substituted evidence ids are hidden", "content": { "application/json": { "schema": { "oneOf": [ { "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "error_code": { "type": "string", "nullable": true }, "errors": { "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/sales-invoices/{documentId}/attachments/{attachmentId}": { "delete": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "Soft-delete an attachment on a sales invoice", "description": "Soft-deletes the attachment metadata. The blob is retained. Author or company admin (AuthorizationPolicy::isAdmin) may delete.", "operationId": "8d3a4a45d50d319085959f963497df2a", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "attachmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Attachment soft-deleted" }, "403": { "description": "Actor is not the uploader and is not an admin", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Forbidden" }, "status": { "type": "integer", "example": 403 }, "error_code": { "type": "string", "example": "attachment_deletion_not_allowed" } }, "type": "object" } } } }, "404": { "description": "Document or attachment not found, or a path id that is not a UUID, which the router answers before the controller with a `message` body.", "content": { "application/json": { "schema": { "oneOf": [ { "required": [ "title", "status", "error_code" ], "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "error_code": { "type": "string", "example": "attachment_not_found" } }, "type": "object" }, { "required": [ "message" ], "properties": { "message": { "type": "string" } }, "type": "object" } ] } } } }, "401": { "description": "Unauthenticated" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/sales-orders/{documentId}/attachments/{attachmentId}": { "delete": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "Soft-delete an attachment on a sales order", "description": "Soft-deletes the attachment metadata. The blob is retained. Author or company admin (AuthorizationPolicy::isAdmin) may delete.", "operationId": "e06b63e15267d6b7bbdea0b9d0087cb9", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "attachmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Attachment soft-deleted" }, "403": { "description": "Actor is not the uploader and is not an admin", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Forbidden" }, "status": { "type": "integer", "example": 403 }, "error_code": { "type": "string", "example": "attachment_deletion_not_allowed" } }, "type": "object" } } } }, "404": { "description": "Document or attachment not found", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "error_code": { "type": "string", "example": "attachment_not_found" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/contracts/{documentId}/attachments/{attachmentId}": { "delete": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "AttachmentDelete on a Purchase Contract", "description": "Soft-deletes the attachment metadata. The blob is retained. Author or company admin (AuthorizationPolicy::isAdmin) may delete.", "operationId": "7eb713b968134a1d1ef86e83c2028340", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "attachmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Attachment soft-deleted" }, "403": { "description": "Forbidden: permission, membership or evidence ownership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } ] } } } }, "404": { "description": "Document or scoped evidence not found", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/contract-activations/{documentId}/attachments/{attachmentId}": { "delete": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "AttachmentDelete on a Purchase Contract Activation", "description": "Soft-deletes the attachment metadata. The blob is retained. Author or company admin (AuthorizationPolicy::isAdmin) may delete.", "operationId": "bed42a74905ae213a9533e21a4fc4455", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "attachmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Attachment soft-deleted" }, "403": { "description": "Forbidden: permission, membership or evidence ownership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } ] } } } }, "404": { "description": "Document or scoped evidence not found", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/contract-addenda/{documentId}/attachments/{attachmentId}": { "delete": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "AttachmentDelete on a Purchase Contract Addendum", "description": "Soft-deletes the attachment metadata. The blob is retained. Author or company admin (AuthorizationPolicy::isAdmin) may delete.", "operationId": "e09aa5aaeaf123c48657d189b5435597", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "attachmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Attachment soft-deleted" }, "403": { "description": "Forbidden: permission, membership or evidence ownership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } ] } } } }, "404": { "description": "Document or scoped evidence not found", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/contract-deactivations/{documentId}/attachments/{attachmentId}": { "delete": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "AttachmentDelete on a Purchase Contract Deactivation", "description": "Soft-deletes the attachment metadata. The blob is retained. Author or company admin (AuthorizationPolicy::isAdmin) may delete.", "operationId": "56d3934d54dffe0b593ef9417483c743", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "attachmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Attachment soft-deleted" }, "403": { "description": "Forbidden: permission, membership or evidence ownership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } ] } } } }, "404": { "description": "Document or scoped evidence not found", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/contracts/{contractId}/attachments/{attachmentId}": { "delete": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "AttachmentDelete on a Sales Contract", "description": "Soft-deletes the attachment metadata. The blob is retained. Author or company admin (AuthorizationPolicy::isAdmin) may delete.", "operationId": "28a781e22a072325a08f40fde67c44af", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "contractId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "attachmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Attachment soft-deleted" }, "403": { "description": "Forbidden: permission, membership or evidence ownership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractProblemResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareForbiddenResponse" } ] } } } }, "404": { "description": "Document or scoped evidence not found", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractProblemResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/contract-activations/{activationId}/attachments/{attachmentId}": { "delete": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "AttachmentDelete on a Sales Contract Activation", "description": "Soft-deletes the attachment metadata. The blob is retained. Author or company admin (AuthorizationPolicy::isAdmin) may delete.", "operationId": "103d8ae18b1afe439e0b7068bfe67efd", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "activationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "attachmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Attachment soft-deleted" }, "403": { "description": "Forbidden: permission, membership or evidence ownership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractProblemResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareForbiddenResponse" } ] } } } }, "404": { "description": "Document or scoped evidence not found", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractProblemResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/contract-deactivations/{deactivationId}/attachments/{attachmentId}": { "delete": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "AttachmentDelete on a Sales Contract Deactivation", "description": "Soft-deletes the attachment metadata. The blob is retained. Author or company admin (AuthorizationPolicy::isAdmin) may delete.", "operationId": "b22fb830b9420952cda65e582fcc3e08", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "deactivationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "attachmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Attachment soft-deleted" }, "403": { "description": "Forbidden: permission, membership or evidence ownership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractProblemResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareForbiddenResponse" } ] } } } }, "404": { "description": "Document or scoped evidence not found", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractProblemResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/potential-customers/{potentialCustomerId}/attachments/{attachmentId}": { "delete": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "AttachmentDelete on a Potential Customer", "description": "Soft-deletes the attachment metadata. The blob is retained. Author or company admin (AuthorizationPolicy::isAdmin) may delete.", "operationId": "420d97b58ad44bdc704b0b5ab5e079f5", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "potentialCustomerId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "attachmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Attachment soft-deleted" }, "403": { "description": "Forbidden: permission, membership or evidence ownership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractProblemResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareForbiddenResponse" } ] } } } }, "404": { "description": "Document or scoped evidence not found", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractProblemResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/transfers/{documentId}/attachments/{attachmentId}": { "delete": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "Soft-delete an attachment on an inventory transfer (Traslado de inventario)", "description": "Soft-deletes the attachment metadata. The blob is retained. Author or company admin (AuthorizationPolicy::isAdmin) may delete.", "operationId": "f0d6e81b387d2f48e53fba528b4f2d24", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "attachmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Attachment soft-deleted" }, "403": { "description": "Actor is not the uploader and is not an admin", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Forbidden" }, "status": { "type": "integer", "example": 403 }, "error_code": { "type": "string", "example": "attachment_deletion_not_allowed" } }, "type": "object" } } } }, "404": { "description": "Document or attachment not found", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "error_code": { "type": "string", "example": "attachment_not_found" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/treasury/transfers/{documentId}/attachments/{attachmentId}": { "delete": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "Soft-delete an attachment on a treasury transfer (transferencia entre cuentas propias)", "description": "Soft-deletes the attachment metadata. The blob is retained. Author or company admin (AuthorizationPolicy::isAdmin) may delete. Requires `backoffice.treasury.treasury-transfers.view`.", "operationId": "52e0b5894c1d3f45abf04cae8c2b8c49", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "attachmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Attachment soft-deleted" }, "403": { "description": "Actor is not the uploader and is not an admin", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Forbidden" }, "status": { "type": "integer", "example": 403 }, "error_code": { "type": "string", "example": "attachment_deletion_not_allowed" } }, "type": "object" } } } }, "404": { "description": "Document or attachment not found", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "error_code": { "type": "string", "example": "attachment_not_found" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/dispatches/{documentId}/attachments/{attachmentId}": { "delete": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "Soft-delete an attachment on an inventory dispatch (Despacho de inventario)", "description": "Soft-deletes the attachment metadata. The blob is retained. Author or company admin (AuthorizationPolicy::isAdmin) may delete.", "operationId": "7b47597ab3523078129c0161d1efd69e", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "attachmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Attachment soft-deleted" }, "403": { "description": "HTTP 403; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryDispatchForbidden" } } } }, "404": { "description": "HTTP 404; document, child and company scope are enforced", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/InventoryDispatchProblem" }, { "$ref": "#/components/schemas/InventoryDispatchUnauthenticated" } ] } } } }, "401": { "description": "HTTP 401; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryDispatchUnauthenticated" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/entries/{documentId}/attachments/{attachmentId}": { "delete": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "Soft-delete an attachment on an inventory entry (Entrada de inventario)", "description": "Soft-deletes the attachment metadata. The blob is retained. Author or company admin (AuthorizationPolicy::isAdmin) may delete.", "operationId": "b122d39c1b122d6f9023ed4b01c4bbfa", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "attachmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Attachment soft-deleted" }, "403": { "description": "HTTP 403; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryEntryForbidden" } } } }, "404": { "description": "HTTP 404; document, child and company scope are enforced", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/InventoryEntryProblem" }, { "$ref": "#/components/schemas/InventoryEntryUnauthenticated" } ] } } } }, "401": { "description": "HTTP 401; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryEntryUnauthenticated" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/transformations/{documentId}/attachments/{attachmentId}": { "delete": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "Soft-delete an attachment on a transformation (Transformación de ítems)", "description": "Soft-deletes the attachment metadata. The blob is retained. Author or company admin (AuthorizationPolicy::isAdmin) may delete.", "operationId": "90f2403189e14cb1455d1cbb8c13872a", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "attachmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Attachment soft-deleted" }, "403": { "description": "HTTP 403; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransformationForbidden" } } } }, "404": { "description": "HTTP 404; document, child and company scope are enforced", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/TransformationProblem" }, { "$ref": "#/components/schemas/TransformationUnauthenticated" } ] } } } }, "401": { "description": "HTTP 401; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransformationUnauthenticated" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/adjustments/{documentId}/attachments/{attachmentId}": { "delete": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "Soft-delete an attachment on an inventory adjustment (Ajuste de inventario)", "description": "Soft-deletes the attachment metadata. The blob is retained. Author or company admin (AuthorizationPolicy::isAdmin) may delete.", "operationId": "eb48f5898933b72109f9a1b051a54056", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "attachmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Attachment soft-deleted" }, "403": { "description": "HTTP 403; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdjustmentForbidden" } } } }, "404": { "description": "HTTP 404; document, child and company scope are enforced", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/AdjustmentProblem" }, { "$ref": "#/components/schemas/AdjustmentUnauthenticated" } ] } } } }, "401": { "description": "HTTP 401; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdjustmentUnauthenticated" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/credit-notes/{documentId}/attachments/{attachmentId}": { "delete": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "Soft-delete an attachment on a supplier nota de crédito de proveedor", "description": "Requires `backoffice.purchases.credit-notes.view`. Soft-deletes the attachment metadata. The blob is retained. Uploader or company admin may delete.", "operationId": "8844ffe450e65f305e871792796ccbe8", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "attachmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Attachment soft-deleted" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden: missing backoffice.purchases.credit-notes.view or not allowed to delete" }, "404": { "description": "Document or attachment not found" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/debit-notes/{documentId}/attachments/{attachmentId}": { "delete": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "Soft-delete an attachment on a supplier nota de débito de proveedor", "description": "Requires `backoffice.purchases.debit-notes.view`. Soft-deletes the attachment metadata. The blob is retained. Uploader or company admin may delete.", "operationId": "498f4efb9ac284d7a2157356301bfd10", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "attachmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Attachment soft-deleted" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden: missing backoffice.purchases.debit-notes.view or not allowed to delete" }, "404": { "description": "Document or attachment not found" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/fiscal/tax-declarations/{documentId}/attachments/{attachmentId}/download": { "get": { "tags": [ "Backoffice - Fiscal - Tax Declarations" ], "summary": "Download a file attached to a tax declaration", "description": "Requires backoffice.fiscal.declarations.view.", "operationId": "31398a5abeb1a6bd1d01224c5e22b6b8", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "documentId", "in": "path", "description": "The tax declaration id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "attachmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "A temporary download URL", "content": { "application/json": { "schema": { "required": [ "url", "expires_at" ], "properties": { "url": { "type": "string", "format": "uri" }, "expires_at": { "type": "string", "format": "date-time" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Missing backoffice.fiscal.declarations.view" }, "404": { "description": "Tax declaration or attachment not found" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/treasury/bank-reconciliations/{documentId}/attachments/{attachmentId}/download": { "get": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "Get a temporary download URL of a month's bank reconciliation evidence", "description": "Requires backoffice.treasury.bank-reconciliations.view and company membership. The reconciliation month and the evidence ids must belong to the route company and parent; another company's month reads as absent. Authors/uploaders or company administrators delete their evidence. A missing statement never keeps a month from closing.", "operationId": "13c22775fafad6cb9a7b1d75e2421ab6", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "documentId", "in": "path", "description": "The month's bank reconciliation row (`reconciliation.id`)", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "attachmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "A temporary download URL", "content": { "application/json": { "schema": { "required": [ "url", "expires_at" ], "properties": { "url": { "type": "string", "format": "uri" }, "expires_at": { "type": "string", "format": "date-time" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankStatementMessageError" } } } }, "403": { "description": "Missing backoffice.treasury.bank-reconciliations.view or company membership; actor cannot delete another user's evidence", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/BankStatementProblem" }, { "$ref": "#/components/schemas/BankStatementMiddlewareProblem" } ] } } } }, "404": { "description": "Reconciliation month or attachment not found; foreign parents and substituted evidence ids are hidden", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/BankStatementProblem" }, { "$ref": "#/components/schemas/BankStatementMessageError" } ] } } } }, "503": { "description": "Attachment storage configuration or connection failed (error_code attachment_storage_unavailable)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachmentStorageUnavailableProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/orders/{documentId}/attachments/{attachmentId}/download": { "get": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "Issue a temporary download URL for an attachment", "description": "Returns a signed temporary URL (10 minutes) with Content-Disposition attachment and Content-Type.", "operationId": "285bcf8ba54a00521468df2d540eec84", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "attachmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Temporary download link", "content": { "application/json": { "schema": { "properties": { "url": { "type": "string", "format": "uri" }, "expires_at": { "type": "string", "format": "date-time" } }, "type": "object" } } } }, "404": { "description": "Document or attachment not found", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "error_code": { "type": "string", "example": "attachment_not_found" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "503": { "description": "Attachment storage configuration, connection or signing failed; no download link was issued (error_code attachment_storage_unavailable)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachmentStorageUnavailableProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/purchases-orders/{documentId}/attachments/{attachmentId}/download": { "get": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "Issue a temporary download URL for an attachment on a purchase order (Orden de compra)", "description": "Returns a signed temporary URL (10 minutes) with Content-Disposition attachment and Content-Type.", "operationId": "ff13ba4ab4f6f293e99cfc94ca8395c0", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "attachmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Temporary download link", "content": { "application/json": { "schema": { "properties": { "url": { "type": "string", "format": "uri" }, "expires_at": { "type": "string", "format": "date-time" } }, "type": "object" } } } }, "404": { "description": "Document or attachment not found", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "error_code": { "type": "string", "example": "attachment_not_found" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "503": { "description": "Attachment storage configuration, connection or signing failed; no download link was issued (error_code attachment_storage_unavailable)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachmentStorageUnavailableProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/providers/{documentId}/attachments/{attachmentId}/download": { "get": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "Issue a temporary download URL for an attachment", "description": "Requires `backoffice.purchases.providers.view`. Returns a signed temporary URL (10 minutes) with Content-Disposition attachment and Content-Type.", "operationId": "93a4a1c38ff5a51fde55ade10b290a3c", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "attachmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Temporary download link", "content": { "application/json": { "schema": { "properties": { "url": { "type": "string", "format": "uri" }, "expires_at": { "type": "string", "format": "date-time" } }, "type": "object" } } } }, "404": { "description": "Document or attachment not found", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "error_code": { "type": "string", "example": "attachment_not_found" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "503": { "description": "Attachment storage configuration, connection or signing failed; no download link was issued (error_code attachment_storage_unavailable)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachmentStorageUnavailableProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/collections/{documentId}/attachments/{attachmentId}/download": { "get": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "Get a temporary collection evidence download URL", "description": "Requires collections.view and company membership. The parent Collection and evidence ids must belong to the route company and parent. Comments are plain text. Authors alone edit comments; authors/uploaders or company administrators delete their evidence. A screenshot reports payment evidence and never sets or confirms the informational crediting date.", "operationId": "550da4052421faa5042d90b73c6d8d10", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "attachmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Get a temporary collection evidence download URL", "content": { "application/json": { "schema": { "required": [ "url", "expires_at" ], "properties": { "url": { "type": "string", "format": "uri" }, "expires_at": { "type": "string", "format": "date-time" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "oneOf": [ { "required": [ "message" ], "properties": { "message": { "type": "string" } }, "type": "object" } ] } } } }, "403": { "description": "Missing collections.view or company membership; actor cannot edit/delete another user evidence or attach to another user comment", "content": { "application/json": { "schema": { "oneOf": [ { "required": [ "message" ], "properties": { "message": { "type": "string" } }, "type": "object" }, { "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "error_code": { "type": "string", "nullable": true }, "errors": { "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" } ] } } } }, "404": { "description": "Collection, scoped comment or attachment not found; foreign parents and substituted evidence ids are hidden", "content": { "application/json": { "schema": { "oneOf": [ { "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "error_code": { "type": "string", "nullable": true }, "errors": { "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" } ] } } } }, "503": { "description": "Attachment storage configuration, connection or signing failed; no download link was issued (error_code attachment_storage_unavailable)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachmentStorageUnavailableProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/sales-invoices/{documentId}/attachments/{attachmentId}/download": { "get": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "Issue a temporary download URL for an attachment", "description": "Returns a signed temporary URL (10 minutes) with Content-Disposition attachment and Content-Type.", "operationId": "91545bde085ba8ab30a47ba4dfa6d5ac", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "attachmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Temporary download link", "content": { "application/json": { "schema": { "properties": { "url": { "type": "string", "format": "uri" }, "expires_at": { "type": "string", "format": "date-time" } }, "type": "object" } } } }, "404": { "description": "Document or attachment not found, or a path id that is not a UUID, which the router answers before the controller with a `message` body.", "content": { "application/json": { "schema": { "oneOf": [ { "required": [ "title", "status", "error_code" ], "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "error_code": { "type": "string", "example": "attachment_not_found" } }, "type": "object" }, { "required": [ "message" ], "properties": { "message": { "type": "string" } }, "type": "object" } ] } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "503": { "description": "Attachment storage configuration, connection or signing failed; no download link was issued (error_code attachment_storage_unavailable)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachmentStorageUnavailableProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/sales-orders/{documentId}/attachments/{attachmentId}/download": { "get": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "Issue a temporary download URL for an attachment", "description": "Returns a signed temporary URL (10 minutes) with Content-Disposition attachment and Content-Type.", "operationId": "6748bf179d4a30b52ea9fcaf7b8a2bdd", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "attachmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Temporary download link", "content": { "application/json": { "schema": { "properties": { "url": { "type": "string", "format": "uri" }, "expires_at": { "type": "string", "format": "date-time" } }, "type": "object" } } } }, "404": { "description": "Document or attachment not found", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "error_code": { "type": "string", "example": "attachment_not_found" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "503": { "description": "Attachment storage configuration, connection or signing failed; no download link was issued (error_code attachment_storage_unavailable)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachmentStorageUnavailableProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/contracts/{documentId}/attachments/{attachmentId}/download": { "get": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "AttachmentDownloadGet on a Purchase Contract", "description": "Returns a signed temporary URL (10 minutes) with Content-Disposition attachment and Content-Type.", "operationId": "6f1862745d43e9f9c589a9dbb6a557ca", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "attachmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Temporary download link", "content": { "application/json": { "schema": { "properties": { "url": { "type": "string", "format": "uri" }, "expires_at": { "type": "string", "format": "date-time" } }, "type": "object" } } } }, "404": { "description": "Document or scoped evidence not found", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } } } }, "403": { "description": "Forbidden: permission, membership or evidence ownership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } ] } } } }, "503": { "description": "Attachment storage configuration, connection or signing failed; no download link was issued (error_code attachment_storage_unavailable)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachmentStorageUnavailableProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/contract-activations/{documentId}/attachments/{attachmentId}/download": { "get": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "AttachmentDownloadGet on a Purchase Contract Activation", "description": "Returns a signed temporary URL (10 minutes) with Content-Disposition attachment and Content-Type.", "operationId": "1c42c07407c7bd75853a76f1be9b17dc", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "attachmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Temporary download link", "content": { "application/json": { "schema": { "properties": { "url": { "type": "string", "format": "uri" }, "expires_at": { "type": "string", "format": "date-time" } }, "type": "object" } } } }, "404": { "description": "Document or scoped evidence not found", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } } } }, "403": { "description": "Forbidden: permission, membership or evidence ownership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } ] } } } }, "503": { "description": "Attachment storage configuration, connection or signing failed; no download link was issued (error_code attachment_storage_unavailable)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachmentStorageUnavailableProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/contract-addenda/{documentId}/attachments/{attachmentId}/download": { "get": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "AttachmentDownloadGet on a Purchase Contract Addendum", "description": "Returns a signed temporary URL (10 minutes) with Content-Disposition attachment and Content-Type.", "operationId": "edc6b4b85775883253d3b368bf78a3ae", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "attachmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Temporary download link", "content": { "application/json": { "schema": { "properties": { "url": { "type": "string", "format": "uri" }, "expires_at": { "type": "string", "format": "date-time" } }, "type": "object" } } } }, "404": { "description": "Document or scoped evidence not found", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } } } }, "403": { "description": "Forbidden: permission, membership or evidence ownership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } ] } } } }, "503": { "description": "Attachment storage configuration, connection or signing failed; no download link was issued (error_code attachment_storage_unavailable)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachmentStorageUnavailableProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/contract-deactivations/{documentId}/attachments/{attachmentId}/download": { "get": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "AttachmentDownloadGet on a Purchase Contract Deactivation", "description": "Returns a signed temporary URL (10 minutes) with Content-Disposition attachment and Content-Type.", "operationId": "b4dbb5bed901ed27cb7e2274625ad26a", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "attachmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Temporary download link", "content": { "application/json": { "schema": { "properties": { "url": { "type": "string", "format": "uri" }, "expires_at": { "type": "string", "format": "date-time" } }, "type": "object" } } } }, "404": { "description": "Document or scoped evidence not found", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } } } }, "403": { "description": "Forbidden: permission, membership or evidence ownership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } ] } } } }, "503": { "description": "Attachment storage configuration, connection or signing failed; no download link was issued (error_code attachment_storage_unavailable)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachmentStorageUnavailableProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/contracts/{contractId}/attachments/{attachmentId}/download": { "get": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "AttachmentDownloadGet on a Sales Contract", "description": "Returns a signed temporary URL (10 minutes) with Content-Disposition attachment and Content-Type.", "operationId": "fff1721f557f731762d22c0689eea157", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "contractId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "attachmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Temporary download link", "content": { "application/json": { "schema": { "properties": { "url": { "type": "string", "format": "uri" }, "expires_at": { "type": "string", "format": "date-time" } }, "type": "object" } } } }, "404": { "description": "Document or scoped evidence not found", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractProblemResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } } } }, "403": { "description": "Forbidden: permission, membership or evidence ownership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractProblemResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareForbiddenResponse" } ] } } } }, "503": { "description": "Attachment storage configuration, connection or signing failed; no download link was issued (error_code attachment_storage_unavailable)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachmentStorageUnavailableProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/contract-activations/{activationId}/attachments/{attachmentId}/download": { "get": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "AttachmentDownloadGet on a Sales Contract Activation", "description": "Returns a signed temporary URL (10 minutes) with Content-Disposition attachment and Content-Type.", "operationId": "42015a57360883ca67444d71af65345a", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "activationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "attachmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Temporary download link", "content": { "application/json": { "schema": { "properties": { "url": { "type": "string", "format": "uri" }, "expires_at": { "type": "string", "format": "date-time" } }, "type": "object" } } } }, "404": { "description": "Document or scoped evidence not found", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractProblemResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } } } }, "403": { "description": "Forbidden: permission, membership or evidence ownership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractProblemResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareForbiddenResponse" } ] } } } }, "503": { "description": "Attachment storage configuration, connection or signing failed; no download link was issued (error_code attachment_storage_unavailable)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachmentStorageUnavailableProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/contract-deactivations/{deactivationId}/attachments/{attachmentId}/download": { "get": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "AttachmentDownloadGet on a Sales Contract Deactivation", "description": "Returns a signed temporary URL (10 minutes) with Content-Disposition attachment and Content-Type.", "operationId": "1225121af2d1940fef8d96f58d071e18", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "deactivationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "attachmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Temporary download link", "content": { "application/json": { "schema": { "properties": { "url": { "type": "string", "format": "uri" }, "expires_at": { "type": "string", "format": "date-time" } }, "type": "object" } } } }, "404": { "description": "Document or scoped evidence not found", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractProblemResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } } } }, "403": { "description": "Forbidden: permission, membership or evidence ownership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractProblemResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareForbiddenResponse" } ] } } } }, "503": { "description": "Attachment storage configuration, connection or signing failed; no download link was issued (error_code attachment_storage_unavailable)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachmentStorageUnavailableProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/potential-customers/{potentialCustomerId}/attachments/{attachmentId}/download": { "get": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "AttachmentDownloadGet on a Potential Customer", "description": "Returns a signed temporary URL (10 minutes) with Content-Disposition attachment and Content-Type.", "operationId": "637aa7979a62b2afdb86fe008d8beb12", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "potentialCustomerId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "attachmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Temporary download link", "content": { "application/json": { "schema": { "properties": { "url": { "type": "string", "format": "uri" }, "expires_at": { "type": "string", "format": "date-time" } }, "type": "object" } } } }, "404": { "description": "Document or scoped evidence not found", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractProblemResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } } } }, "403": { "description": "Forbidden: permission, membership or evidence ownership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractProblemResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareForbiddenResponse" } ] } } } }, "503": { "description": "Attachment storage configuration, connection or signing failed; no download link was issued (error_code attachment_storage_unavailable)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachmentStorageUnavailableProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/transfers/{documentId}/attachments/{attachmentId}/download": { "get": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "Issue a temporary download URL for an attachment on an inventory transfer (Traslado de inventario)", "description": "Returns a signed temporary URL (10 minutes) with Content-Disposition attachment and Content-Type.", "operationId": "471299bb5189a3af3be576798530f0e4", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "attachmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Temporary download link", "content": { "application/json": { "schema": { "properties": { "url": { "type": "string", "format": "uri" }, "expires_at": { "type": "string", "format": "date-time" } }, "type": "object" } } } }, "404": { "description": "Document or attachment not found", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "error_code": { "type": "string", "example": "attachment_not_found" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "503": { "description": "Attachment storage configuration, connection or signing failed; no download link was issued (error_code attachment_storage_unavailable)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachmentStorageUnavailableProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/treasury/transfers/{documentId}/attachments/{attachmentId}/download": { "get": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "Issue a temporary download URL for an attachment on a treasury transfer (transferencia entre cuentas propias)", "description": "Returns a signed temporary URL (10 minutes) with Content-Disposition attachment and Content-Type. Requires `backoffice.treasury.treasury-transfers.view`.", "operationId": "8fd6a09293dd44001a1607319223ca5f", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "attachmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Temporary download link", "content": { "application/json": { "schema": { "properties": { "url": { "type": "string", "format": "uri" }, "expires_at": { "type": "string", "format": "date-time" } }, "type": "object" } } } }, "404": { "description": "Document or attachment not found", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "error_code": { "type": "string", "example": "attachment_not_found" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "503": { "description": "Attachment storage configuration, connection or signing failed; no download link was issued (error_code attachment_storage_unavailable)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachmentStorageUnavailableProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/dispatches/{documentId}/attachments/{attachmentId}/download": { "get": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "Issue a temporary download URL for an attachment on an inventory dispatch (Despacho de inventario)", "description": "Returns a signed temporary URL (10 minutes) with Content-Disposition attachment and Content-Type.", "operationId": "e4a612108da859899bd9ebd79f031cef", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "attachmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Temporary download link", "content": { "application/json": { "schema": { "properties": { "url": { "type": "string", "format": "uri" }, "expires_at": { "type": "string", "format": "date-time" } }, "type": "object" } } } }, "404": { "description": "HTTP 404; document, child and company scope are enforced", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/InventoryDispatchProblem" }, { "$ref": "#/components/schemas/InventoryDispatchUnauthenticated" } ] } } } }, "401": { "description": "HTTP 401; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryDispatchUnauthenticated" } } } }, "403": { "description": "HTTP 403; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryDispatchForbidden" } } } }, "503": { "description": "Attachment storage configuration, connection or signing failed; no download link was issued (error_code attachment_storage_unavailable)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachmentStorageUnavailableProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/entries/{documentId}/attachments/{attachmentId}/download": { "get": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "Issue a temporary download URL for an attachment on an inventory entry (Entrada de inventario)", "description": "Returns a signed temporary URL (10 minutes) with Content-Disposition attachment and Content-Type.", "operationId": "2da2ad7140421e50f3640eb246785bd4", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "attachmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Temporary download link", "content": { "application/json": { "schema": { "properties": { "url": { "type": "string", "format": "uri" }, "expires_at": { "type": "string", "format": "date-time" } }, "type": "object" } } } }, "404": { "description": "HTTP 404; document, child and company scope are enforced", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/InventoryEntryProblem" }, { "$ref": "#/components/schemas/InventoryEntryUnauthenticated" } ] } } } }, "401": { "description": "HTTP 401; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryEntryUnauthenticated" } } } }, "403": { "description": "HTTP 403; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryEntryForbidden" } } } }, "503": { "description": "Attachment storage configuration, connection or signing failed; no download link was issued (error_code attachment_storage_unavailable)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachmentStorageUnavailableProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/transformations/{documentId}/attachments/{attachmentId}/download": { "get": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "Issue a temporary download URL for an attachment on a transformation (Transformación de ítems)", "description": "Returns a signed temporary URL (10 minutes) with Content-Disposition attachment and Content-Type.", "operationId": "7430e40107f46fa1879c401f58f951cd", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "attachmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Temporary download link", "content": { "application/json": { "schema": { "properties": { "url": { "type": "string", "format": "uri" }, "expires_at": { "type": "string", "format": "date-time" } }, "type": "object" } } } }, "404": { "description": "HTTP 404; document, child and company scope are enforced", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/TransformationProblem" }, { "$ref": "#/components/schemas/TransformationUnauthenticated" } ] } } } }, "401": { "description": "HTTP 401; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransformationUnauthenticated" } } } }, "403": { "description": "HTTP 403; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransformationForbidden" } } } }, "503": { "description": "Attachment storage configuration, connection or signing failed; no download link was issued (error_code attachment_storage_unavailable)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachmentStorageUnavailableProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/adjustments/{documentId}/attachments/{attachmentId}/download": { "get": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "Issue a temporary download URL for an attachment on an inventory adjustment (Ajuste de inventario)", "description": "Returns a signed temporary URL (10 minutes) with Content-Disposition attachment and Content-Type.", "operationId": "8117c3980826ee077d1fd5c00ee74cda", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "attachmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Temporary download link", "content": { "application/json": { "schema": { "properties": { "url": { "type": "string", "format": "uri" }, "expires_at": { "type": "string", "format": "date-time" } }, "type": "object" } } } }, "404": { "description": "HTTP 404; document, child and company scope are enforced", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/AdjustmentProblem" }, { "$ref": "#/components/schemas/AdjustmentUnauthenticated" } ] } } } }, "401": { "description": "HTTP 401; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdjustmentUnauthenticated" } } } }, "403": { "description": "HTTP 403; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdjustmentForbidden" } } } }, "503": { "description": "Attachment storage configuration, connection or signing failed; no download link was issued (error_code attachment_storage_unavailable)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachmentStorageUnavailableProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/credit-notes/{documentId}/attachments/{attachmentId}/download": { "get": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "Download an attachment on a supplier nota de crédito de proveedor", "description": "Requires `backoffice.purchases.credit-notes.view`. Returns a signed temporary URL (10 minutes) with Content-Disposition attachment and Content-Type.", "operationId": "9eed506daad5d0c79ec4ee8104a3cda5", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "attachmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Temporary download link", "content": { "application/json": { "schema": { "properties": { "url": { "type": "string", "format": "uri" }, "expires_at": { "type": "string", "format": "date-time" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks backoffice.purchases.credit-notes.view" }, "404": { "description": "Document or attachment not found" }, "503": { "description": "Attachment storage unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachmentStorageUnavailableProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/debit-notes/{documentId}/attachments/{attachmentId}/download": { "get": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "Download an attachment on a supplier nota de débito de proveedor", "description": "Requires `backoffice.purchases.debit-notes.view`. Returns a signed temporary URL (10 minutes) with Content-Disposition attachment and Content-Type.", "operationId": "6cf20c6db2e94d8d8107ece52dc4b9aa", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "attachmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Temporary download link", "content": { "application/json": { "schema": { "properties": { "url": { "type": "string", "format": "uri" }, "expires_at": { "type": "string", "format": "date-time" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks backoffice.purchases.debit-notes.view" }, "404": { "description": "Document or attachment not found" }, "503": { "description": "Attachment storage unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachmentStorageUnavailableProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/fiscal/tax-declarations/{documentId}/attachments": { "get": { "tags": [ "Backoffice - Fiscal - Tax Declarations" ], "summary": "List files attached to a tax declaration", "description": "Requires backoffice.fiscal.declarations.view.", "operationId": "f6c29aa83baea41079427926c56f24b5", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "documentId", "in": "path", "description": "The tax declaration id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The attachments, oldest first" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Missing backoffice.fiscal.declarations.view" }, "404": { "description": "Tax declaration not found" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Fiscal - Tax Declarations" ], "summary": "Attach a file to a tax declaration", "description": "Requires backoffice.fiscal.declarations.manage. The declaration must belong to the route company.", "operationId": "4876c1b282f251046c41c06990894baf", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "documentId", "in": "path", "description": "The tax declaration id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "id", "file" ], "properties": { "id": { "description": "Client-supplied UUIDv7", "type": "string", "format": "uuid" }, "file": { "description": "Maximum 15 MiB. Matching MIME and extension: PDF, JPG/JPEG, PNG, WEBP, XLSX, CSV or DOCX.", "type": "string", "format": "binary" } }, "type": "object" } } } }, "responses": { "201": { "description": "File attached" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Missing backoffice.fiscal.declarations.manage" }, "404": { "description": "Tax declaration not found" }, "409": { "description": "attachment_already_exists" }, "422": { "description": "Invalid attachment" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/treasury/bank-reconciliations/{documentId}/attachments": { "get": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "List the evidence attached to a month's bank reconciliation", "description": "Requires backoffice.treasury.bank-reconciliations.view and company membership. The reconciliation month and the evidence ids must belong to the route company and parent; another company's month reads as absent. Authors/uploaders or company administrators delete their evidence. A missing statement never keeps a month from closing.", "operationId": "347a5da4da5dd6c6a9ce3e01c24b3baf", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "documentId", "in": "path", "description": "The month's bank reconciliation row (`reconciliation.id`)", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The evidence, oldest first", "content": { "application/json": { "schema": { "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "original_name": { "type": "string" }, "mime_type": { "type": "string" }, "size_bytes": { "type": "integer" }, "uploaded_by": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "comment_id": { "type": "string", "format": "uuid", "nullable": true }, "can_delete": { "type": "boolean" } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankStatementMessageError" } } } }, "403": { "description": "Missing backoffice.treasury.bank-reconciliations.view or company membership; actor cannot delete another user's evidence", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/BankStatementProblem" }, { "$ref": "#/components/schemas/BankStatementMiddlewareProblem" } ] } } } }, "404": { "description": "Reconciliation month or attachment not found; foreign parents and substituted evidence ids are hidden", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/BankStatementProblem" }, { "$ref": "#/components/schemas/BankStatementMessageError" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "Attach evidence, such as the bank statement, to a month's bank reconciliation", "description": "Requires backoffice.treasury.bank-reconciliations.view and company membership. The reconciliation month and the evidence ids must belong to the route company and parent; another company's month reads as absent. Authors/uploaders or company administrators delete their evidence. A missing statement never keeps a month from closing.", "operationId": "bb2e44e07e32d3f72d80e1037815819d", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "documentId", "in": "path", "description": "The month's bank reconciliation row (`reconciliation.id`)", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "id", "file" ], "properties": { "id": { "description": "Client-supplied UUIDv7", "type": "string", "format": "uuid" }, "file": { "description": "Maximum 15 MiB. Matching MIME and extension: PDF, JPG/JPEG, PNG, WEBP, XLSX, CSV or DOCX.", "type": "string", "format": "binary" }, "comment_id": { "description": "Optional existing comment authored by the uploader on this document", "type": "string", "format": "uuid", "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Evidence attached" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankStatementMessageError" } } } }, "403": { "description": "Missing backoffice.treasury.bank-reconciliations.view or company membership; actor cannot delete another user's evidence", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/BankStatementProblem" }, { "$ref": "#/components/schemas/BankStatementMiddlewareProblem" } ] } } } }, "404": { "description": "Reconciliation month or attachment not found; foreign parents and substituted evidence ids are hidden", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/BankStatementProblem" }, { "$ref": "#/components/schemas/BankStatementMessageError" } ] } } } }, "409": { "description": "Client-supplied evidence id already exists (attachment_already_exists)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankStatementProblem" } } } }, "413": { "description": "PHP upload/post size limit exceeded" }, "422": { "description": "Field validation errors; invalid attachment type, size or filename", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankStatementProblem" } } } }, "503": { "description": "Attachment storage configuration, connection or write failed; no attachment metadata was stored, the client id stays free (error_code attachment_storage_unavailable)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachmentStorageUnavailableProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/orders/{documentId}/attachments": { "get": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "List attachments on a purchase order (Pedido)", "description": "Returns every non-deleted attachment on the Pedido ordered by created_at ascending. No download URLs — use the download endpoint. `can_delete` is computed for the authenticated actor.", "operationId": "a9549696f0907a1b37dbe24e6aee4945", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Attachment list", "content": { "application/json": { "schema": { "properties": { "items": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "comment_id": { "type": "string", "format": "uuid", "nullable": true }, "original_name": { "type": "string" }, "mime_type": { "type": "string" }, "size_bytes": { "type": "integer" }, "uploaded_by": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "can_delete": { "type": "boolean" } }, "type": "object" } } }, "type": "object" } } } }, "404": { "description": "Document not found", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "error_code": { "type": "string", "example": "collaboration_document_not_found" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "Upload an attachment on a purchase order (Pedido)", "description": "Accepts multipart form-data with a client-supplied UUIDv7 id and a file. Allowed types: pdf, jpg, jpeg, png, webp, xlsx, csv, docx. Max 15 MB. Duplicate ids answer 409.", "operationId": "65367496eb072e4c3df06f4798f613e9", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "id", "file" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "0190b7a0-1111-7222-8333-444455556666" }, "comment_id": { "description": "Optional existing comment authored by the uploading user on this document", "type": "string", "format": "uuid", "nullable": true }, "file": { "description": "Attachment file (pdf/jpg/jpeg/png/webp/xlsx/csv/docx), max 15 MB", "type": "string", "format": "binary" } }, "type": "object" } } } }, "responses": { "201": { "description": "Attachment uploaded" }, "404": { "description": "Document or scoped comment not found", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "error_code": { "type": "string", "example": "collaboration_document_not_found" } }, "type": "object" } } } }, "409": { "description": "Duplicate attachment ID", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "error_code": { "type": "string", "example": "attachment_already_exists" } }, "type": "object" } } } }, "422": { "description": "Laravel field validation or domain type/size/name error", "content": { "application/json": { "schema": { "oneOf": [ { "required": [ "message", "errors" ], "properties": { "message": { "type": "string" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" }, { "required": [ "title", "status", "error_code" ], "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "error_code": { "type": "string", "example": "unsupported_attachment_type" } }, "type": "object" } ] } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Missing permission or comment not authored by actor", "content": { "application/json": { "schema": { "oneOf": [ { "properties": { "message": { "type": "string" } }, "type": "object" }, { "properties": { "title": { "type": "string" }, "status": { "type": "integer", "example": 403 }, "error_code": { "type": "string", "example": "comment_not_authored_by_actor" } }, "type": "object" } ] } } } }, "413": { "description": "Request entity too large (PHP post_max_size)" }, "503": { "description": "Attachment storage configuration, connection or write failed; no attachment metadata was stored, the client id stays free (error_code attachment_storage_unavailable)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachmentStorageUnavailableProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/purchases-invoices/{documentId}/attachments": { "get": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "List attachments on a purchase invoice (Factura)", "description": "Returns every non-deleted attachment on the purchase invoice (Factura) ordered by created_at ascending. No download URLs — use the download endpoint. `can_delete` is computed for the authenticated actor.", "operationId": "347e064a36d9c2bc04f4ae593fad7f45", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Attachment list", "content": { "application/json": { "schema": { "properties": { "items": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "comment_id": { "type": "string", "format": "uuid", "nullable": true }, "original_name": { "type": "string" }, "mime_type": { "type": "string" }, "size_bytes": { "type": "integer" }, "uploaded_by": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "can_delete": { "type": "boolean" } }, "type": "object" } } }, "type": "object" } } } }, "404": { "description": "Document not found, or a path id that is not a UUID, which the router answers before the controller with a `message` body.", "content": { "application/json": { "schema": { "oneOf": [ { "required": [ "title", "status", "error_code" ], "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "error_code": { "type": "string", "example": "collaboration_document_not_found" } }, "type": "object" }, { "required": [ "message" ], "properties": { "message": { "type": "string" } }, "type": "object" } ] } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "Upload an attachment on a purchase invoice (Factura)", "description": "Accepts multipart form-data with a client-supplied UUIDv7 id and a file. Allowed types: pdf, jpg, jpeg, png, webp, xlsx, csv, docx. Max 15 MB. Duplicate ids answer 409.", "operationId": "6b351573eb099d4d726a52b864d0b196", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "id", "file" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "0190b7a0-1111-7222-8333-444455556666" }, "comment_id": { "description": "Optional existing comment authored by the uploading user on this document", "type": "string", "format": "uuid", "nullable": true }, "file": { "description": "Attachment file (pdf/jpg/jpeg/png/webp/xlsx/csv/docx), max 15 MB", "type": "string", "format": "binary" } }, "type": "object" } } } }, "responses": { "201": { "description": "Attachment uploaded" }, "404": { "description": "Document or scoped comment not found, or a path id that is not a UUID, which the router answers before the controller with a `message` body.", "content": { "application/json": { "schema": { "oneOf": [ { "required": [ "title", "status", "error_code" ], "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "error_code": { "type": "string", "example": "collaboration_document_not_found" } }, "type": "object" }, { "required": [ "message" ], "properties": { "message": { "type": "string" } }, "type": "object" } ] } } } }, "409": { "description": "Duplicate attachment ID", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "error_code": { "type": "string", "example": "attachment_already_exists" } }, "type": "object" } } } }, "422": { "description": "Laravel field validation or domain type/size/name error", "content": { "application/json": { "schema": { "oneOf": [ { "required": [ "message", "errors" ], "properties": { "message": { "type": "string" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" }, { "required": [ "title", "status", "error_code" ], "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "error_code": { "type": "string", "example": "unsupported_attachment_type" } }, "type": "object" } ] } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Missing permission or comment not authored by actor", "content": { "application/json": { "schema": { "oneOf": [ { "properties": { "message": { "type": "string" } }, "type": "object" }, { "properties": { "title": { "type": "string" }, "status": { "type": "integer", "example": 403 }, "error_code": { "type": "string", "example": "comment_not_authored_by_actor" } }, "type": "object" } ] } } } }, "413": { "description": "Request entity too large (PHP post_max_size)" }, "503": { "description": "Attachment storage configuration, connection or write failed; no attachment metadata was stored, the client id stays free (error_code attachment_storage_unavailable)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachmentStorageUnavailableProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/payments/{documentId}/attachments": { "get": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "List attachments on a payment (Pago)", "description": "Returns every non-deleted attachment on the payment (Pago) ordered by created_at ascending. No download URLs — use the download endpoint. `can_delete` is computed for the authenticated actor.", "operationId": "611f5d2a83d81c58a7e8b452e787886a", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Attachment list", "content": { "application/json": { "schema": { "properties": { "items": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "comment_id": { "type": "string", "format": "uuid", "nullable": true }, "original_name": { "type": "string" }, "mime_type": { "type": "string" }, "size_bytes": { "type": "integer" }, "uploaded_by": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "can_delete": { "type": "boolean" } }, "type": "object" } } }, "type": "object" } } } }, "404": { "description": "Document not found", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "error_code": { "type": "string", "example": "collaboration_document_not_found" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "Upload an attachment on a payment (Pago)", "description": "Accepts multipart form-data with a client-supplied UUIDv7 id and a file. Allowed types: pdf, jpg, jpeg, png, webp, xlsx, csv, docx. Max 15 MB. Duplicate ids answer 409.", "operationId": "e6017ad0d131460fe6d73fb6a023dfdc", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "id", "file" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "0190b7a0-1111-7222-8333-444455556666" }, "comment_id": { "description": "Optional existing comment authored by the uploading user on this document", "type": "string", "format": "uuid", "nullable": true }, "file": { "description": "Attachment file (pdf/jpg/jpeg/png/webp/xlsx/csv/docx), max 15 MB", "type": "string", "format": "binary" } }, "type": "object" } } } }, "responses": { "201": { "description": "Attachment uploaded" }, "404": { "description": "Document or scoped comment not found", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "error_code": { "type": "string", "example": "collaboration_document_not_found" } }, "type": "object" } } } }, "409": { "description": "Duplicate attachment ID", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "error_code": { "type": "string", "example": "attachment_already_exists" } }, "type": "object" } } } }, "422": { "description": "Laravel field validation or domain type/size/name error", "content": { "application/json": { "schema": { "oneOf": [ { "required": [ "message", "errors" ], "properties": { "message": { "type": "string" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" }, { "required": [ "title", "status", "error_code" ], "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "error_code": { "type": "string", "example": "unsupported_attachment_type" } }, "type": "object" } ] } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Missing permission or comment not authored by actor", "content": { "application/json": { "schema": { "oneOf": [ { "properties": { "message": { "type": "string" } }, "type": "object" }, { "properties": { "title": { "type": "string" }, "status": { "type": "integer", "example": 403 }, "error_code": { "type": "string", "example": "comment_not_authored_by_actor" } }, "type": "object" } ] } } } }, "413": { "description": "Request entity too large (PHP post_max_size)" }, "503": { "description": "Attachment storage configuration, connection or write failed; no attachment metadata was stored, the client id stays free (error_code attachment_storage_unavailable)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachmentStorageUnavailableProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/purchases-orders/{documentId}/attachments": { "get": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "List attachments on a purchase order (Orden de compra)", "description": "Returns every non-deleted attachment on the Orden de compra ordered by created_at ascending. No download URLs — use the download endpoint. `can_delete` is computed for the authenticated actor.", "operationId": "6ef8bf8893e311096de8147eb726f9b4", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Attachment list", "content": { "application/json": { "schema": { "properties": { "items": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "comment_id": { "type": "string", "format": "uuid", "nullable": true }, "original_name": { "type": "string" }, "mime_type": { "type": "string" }, "size_bytes": { "type": "integer" }, "uploaded_by": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "can_delete": { "type": "boolean" } }, "type": "object" } } }, "type": "object" } } } }, "404": { "description": "Document not found", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "error_code": { "type": "string", "example": "collaboration_document_not_found" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "Upload an attachment on a purchase order (Orden de compra)", "description": "Accepts multipart form-data with a client-supplied UUIDv7 id and a file. Allowed types: pdf, jpg, jpeg, png, webp, xlsx, csv, docx. Max 15 MB. Duplicate ids answer 409.", "operationId": "fad650316bf6b7c0e41d1d3e74b8d619", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "id", "file" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "0190b7a0-1111-7222-8333-444455556666" }, "comment_id": { "description": "Optional existing comment authored by the uploading user on this document", "type": "string", "format": "uuid", "nullable": true }, "file": { "description": "Attachment file (pdf/jpg/jpeg/png/webp/xlsx/csv/docx), max 15 MB", "type": "string", "format": "binary" } }, "type": "object" } } } }, "responses": { "201": { "description": "Attachment uploaded" }, "404": { "description": "Document or scoped comment not found", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "error_code": { "type": "string", "example": "collaboration_document_not_found" } }, "type": "object" } } } }, "409": { "description": "Duplicate attachment ID", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "error_code": { "type": "string", "example": "attachment_already_exists" } }, "type": "object" } } } }, "422": { "description": "Laravel field validation or domain type/size/name error", "content": { "application/json": { "schema": { "oneOf": [ { "required": [ "message", "errors" ], "properties": { "message": { "type": "string" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" }, { "required": [ "title", "status", "error_code" ], "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "error_code": { "type": "string", "example": "unsupported_attachment_type" } }, "type": "object" } ] } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Missing permission or comment not authored by actor", "content": { "application/json": { "schema": { "oneOf": [ { "properties": { "message": { "type": "string" } }, "type": "object" }, { "properties": { "title": { "type": "string" }, "status": { "type": "integer", "example": 403 }, "error_code": { "type": "string", "example": "comment_not_authored_by_actor" } }, "type": "object" } ] } } } }, "413": { "description": "Request entity too large (PHP post_max_size)" }, "503": { "description": "Attachment storage configuration, connection or write failed; no attachment metadata was stored, the client id stays free (error_code attachment_storage_unavailable)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachmentStorageUnavailableProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/providers/{documentId}/attachments": { "get": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "List attachments on a provider", "description": "Requiere `backoffice.purchases.providers.view`. Devuelve todos los adjuntos no eliminados del proveedor ordenados por created_at ascendente. Para obtener la URL de descarga, usa el endpoint de descarga. `can_delete` se calcula para el usuario autenticado.", "operationId": "c8d3198015dab375b283259512fd589b", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Attachment list", "content": { "application/json": { "schema": { "properties": { "items": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "comment_id": { "type": "string", "format": "uuid", "nullable": true }, "original_name": { "type": "string" }, "mime_type": { "type": "string" }, "size_bytes": { "type": "integer" }, "uploaded_by": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "can_delete": { "type": "boolean" } }, "type": "object" } } }, "type": "object" } } } }, "404": { "description": "Document not found", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "error_code": { "type": "string", "example": "collaboration_document_not_found" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "Upload an attachment on a provider", "description": "Requires `backoffice.purchases.providers.view`. Accepts multipart form-data with a client-supplied UUIDv7 id and a file. Allowed types: pdf, jpg, jpeg, png, webp, xlsx, csv, docx. Max 15 MB. Duplicate ids answer 409.", "operationId": "00924486f00580060d01117dddbca52c", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "id", "file" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "0190b7a0-1111-7222-8333-444455556666" }, "comment_id": { "description": "Optional existing comment authored by the uploading user on this document", "type": "string", "format": "uuid", "nullable": true }, "file": { "description": "Attachment file (pdf/jpg/jpeg/png/webp/xlsx/csv/docx), max 15 MB", "type": "string", "format": "binary" } }, "type": "object" } } } }, "responses": { "201": { "description": "Attachment uploaded" }, "404": { "description": "Document or scoped comment not found", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "error_code": { "type": "string", "example": "collaboration_document_not_found" } }, "type": "object" } } } }, "409": { "description": "Duplicate attachment ID", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "error_code": { "type": "string", "example": "attachment_already_exists" } }, "type": "object" } } } }, "422": { "description": "Laravel field validation or domain type/size/name error", "content": { "application/json": { "schema": { "oneOf": [ { "required": [ "message", "errors" ], "properties": { "message": { "type": "string" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" }, { "required": [ "title", "status", "error_code" ], "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "error_code": { "type": "string", "example": "unsupported_attachment_type" } }, "type": "object" } ] } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Missing permission or comment not authored by actor", "content": { "application/json": { "schema": { "oneOf": [ { "properties": { "message": { "type": "string" } }, "type": "object" }, { "properties": { "title": { "type": "string" }, "status": { "type": "integer", "example": 403 }, "error_code": { "type": "string", "example": "comment_not_authored_by_actor" } }, "type": "object" } ] } } } }, "413": { "description": "Request entity too large (PHP post_max_size)" }, "503": { "description": "Attachment storage configuration, connection or write failed; no attachment metadata was stored, the client id stays free (error_code attachment_storage_unavailable)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachmentStorageUnavailableProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/collections/{documentId}/attachments": { "get": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "List collection evidence attachments", "description": "Requires collections.view and company membership. The parent Collection and evidence ids must belong to the route company and parent. Comments are plain text. Authors alone edit comments; authors/uploaders or company administrators delete their evidence. A screenshot reports payment evidence and never sets or confirms the informational crediting date.", "operationId": "27250645b0a691b4a6ee104c97a9d2cc", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "List collection evidence attachments", "content": { "application/json": { "schema": { "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "original_name": { "type": "string" }, "mime_type": { "type": "string" }, "size_bytes": { "type": "integer" }, "uploaded_by": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "comment_id": { "type": "string", "format": "uuid", "nullable": true }, "can_delete": { "type": "boolean" } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "oneOf": [ { "required": [ "message" ], "properties": { "message": { "type": "string" } }, "type": "object" } ] } } } }, "403": { "description": "Missing collections.view or company membership; actor cannot edit/delete another user evidence or attach to another user comment", "content": { "application/json": { "schema": { "oneOf": [ { "required": [ "message" ], "properties": { "message": { "type": "string" } }, "type": "object" }, { "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "error_code": { "type": "string", "nullable": true }, "errors": { "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" } ] } } } }, "404": { "description": "Collection, scoped comment or attachment not found; foreign parents and substituted evidence ids are hidden", "content": { "application/json": { "schema": { "oneOf": [ { "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "error_code": { "type": "string", "nullable": true }, "errors": { "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "Upload collection evidence", "description": "Requires collections.view and company membership. The parent Collection and evidence ids must belong to the route company and parent. Comments are plain text. Authors alone edit comments; authors/uploaders or company administrators delete their evidence. A screenshot reports payment evidence and never sets or confirms the informational crediting date.", "operationId": "fab9b816f5402c92cbc4cf1d8656b240", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "id", "file" ], "properties": { "id": { "description": "Client-supplied UUIDv7", "type": "string", "format": "uuid" }, "file": { "description": "Maximum 15 MiB. Matching MIME and extension: PDF, JPG/JPEG, PNG, WEBP, XLSX, CSV or DOCX.", "type": "string", "format": "binary" }, "comment_id": { "description": "Optional existing comment authored by the uploader on this collection", "type": "string", "format": "uuid", "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Upload collection evidence" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "oneOf": [ { "required": [ "message" ], "properties": { "message": { "type": "string" } }, "type": "object" } ] } } } }, "403": { "description": "Missing collections.view or company membership; actor cannot edit/delete another user evidence or attach to another user comment", "content": { "application/json": { "schema": { "oneOf": [ { "required": [ "message" ], "properties": { "message": { "type": "string" } }, "type": "object" }, { "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "error_code": { "type": "string", "nullable": true }, "errors": { "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" } ] } } } }, "404": { "description": "Collection, scoped comment or attachment not found; foreign parents and substituted evidence ids are hidden", "content": { "application/json": { "schema": { "oneOf": [ { "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "error_code": { "type": "string", "nullable": true }, "errors": { "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" } ] } } } }, "422": { "description": "Field validation errors; invalid comment body or attachment type, size or filename", "content": { "application/json": { "schema": { "oneOf": [ { "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "error_code": { "type": "string", "nullable": true }, "errors": { "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" } ] } } } }, "409": { "description": "Client-supplied evidence id already exists", "content": { "application/json": { "schema": { "oneOf": [ { "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "error_code": { "type": "string", "nullable": true }, "errors": { "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" } ] } } } }, "413": { "description": "PHP upload/post size limit exceeded", "content": { "application/json": { "schema": { "oneOf": [ { "required": [ "message" ], "properties": { "message": { "type": "string" } }, "type": "object" } ] } } } }, "503": { "description": "Attachment storage configuration, connection or write failed; no attachment metadata was stored, the client id stays free (error_code attachment_storage_unavailable)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachmentStorageUnavailableProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/sales-invoices/{documentId}/attachments": { "get": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "List attachments on a sales invoice", "description": "Returns every non-deleted attachment on the factura de venta ordered by created_at ascending. No download URLs — use the download endpoint. `can_delete` is computed for the authenticated actor.", "operationId": "1782f18a362235efc4457e9ddcb5ba45", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Attachment list", "content": { "application/json": { "schema": { "properties": { "items": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "comment_id": { "type": "string", "format": "uuid", "nullable": true }, "original_name": { "type": "string" }, "mime_type": { "type": "string" }, "size_bytes": { "type": "integer" }, "uploaded_by": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "can_delete": { "type": "boolean" } }, "type": "object" } } }, "type": "object" } } } }, "404": { "description": "Document not found, or a path id that is not a UUID, which the router answers before the controller with a `message` body.", "content": { "application/json": { "schema": { "oneOf": [ { "required": [ "title", "status", "error_code" ], "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "error_code": { "type": "string", "example": "collaboration_document_not_found" } }, "type": "object" }, { "required": [ "message" ], "properties": { "message": { "type": "string" } }, "type": "object" } ] } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "Upload an attachment on a sales invoice", "description": "Accepts multipart form-data with a client-supplied UUIDv7 id and a file. Allowed types: pdf, jpg, jpeg, png, webp, xlsx, csv, docx. Max 15 MB. Duplicate ids answer 409.", "operationId": "58e657f8274389d061474853f4416823", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "id", "file" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "0190b7a0-1111-7222-8333-444455556666" }, "comment_id": { "description": "Optional existing comment authored by the uploading user on this document", "type": "string", "format": "uuid", "nullable": true }, "file": { "description": "Attachment file (pdf/jpg/jpeg/png/webp/xlsx/csv/docx), max 15 MB", "type": "string", "format": "binary" } }, "type": "object" } } } }, "responses": { "201": { "description": "Attachment uploaded" }, "404": { "description": "Document or scoped comment not found, or a path id that is not a UUID, which the router answers before the controller with a `message` body.", "content": { "application/json": { "schema": { "oneOf": [ { "required": [ "title", "status", "error_code" ], "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "error_code": { "type": "string", "example": "collaboration_document_not_found" } }, "type": "object" }, { "required": [ "message" ], "properties": { "message": { "type": "string" } }, "type": "object" } ] } } } }, "409": { "description": "Duplicate attachment ID", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "error_code": { "type": "string", "example": "attachment_already_exists" } }, "type": "object" } } } }, "422": { "description": "Laravel field validation or domain type/size/name error", "content": { "application/json": { "schema": { "oneOf": [ { "required": [ "message", "errors" ], "properties": { "message": { "type": "string" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" }, { "required": [ "title", "status", "error_code" ], "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "error_code": { "type": "string", "example": "unsupported_attachment_type" } }, "type": "object" } ] } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Missing permission or comment not authored by actor", "content": { "application/json": { "schema": { "oneOf": [ { "properties": { "message": { "type": "string" } }, "type": "object" }, { "properties": { "title": { "type": "string" }, "status": { "type": "integer", "example": 403 }, "error_code": { "type": "string", "example": "comment_not_authored_by_actor" } }, "type": "object" } ] } } } }, "413": { "description": "Request entity too large (PHP post_max_size)" }, "503": { "description": "Attachment storage configuration, connection or write failed; no attachment metadata was stored, the client id stays free (error_code attachment_storage_unavailable)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachmentStorageUnavailableProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/sales-orders/{documentId}/attachments": { "get": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "List attachments on a sales order", "description": "Returns every non-deleted attachment on the orden de venta ordered by created_at ascending. No download URLs — use the download endpoint. `can_delete` is computed for the authenticated actor.", "operationId": "4c541b87a5150b6c60ba1ba51ef87136", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Attachment list", "content": { "application/json": { "schema": { "properties": { "items": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "comment_id": { "type": "string", "format": "uuid", "nullable": true }, "original_name": { "type": "string" }, "mime_type": { "type": "string" }, "size_bytes": { "type": "integer" }, "uploaded_by": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "can_delete": { "type": "boolean" } }, "type": "object" } } }, "type": "object" } } } }, "404": { "description": "Document not found", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "error_code": { "type": "string", "example": "collaboration_document_not_found" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "Upload an attachment on a sales order", "description": "Accepts multipart form-data with a client-supplied UUIDv7 id and a file. Allowed types: pdf, jpg, jpeg, png, webp, xlsx, csv, docx. Max 15 MB. Duplicate ids answer 409.", "operationId": "800bc2c822c06614ca7bc77df8c36dfe", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "id", "file" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "0190b7a0-1111-7222-8333-444455556666" }, "comment_id": { "description": "Optional existing comment authored by the uploading user on this document", "type": "string", "format": "uuid", "nullable": true }, "file": { "description": "Attachment file (pdf/jpg/jpeg/png/webp/xlsx/csv/docx), max 15 MB", "type": "string", "format": "binary" } }, "type": "object" } } } }, "responses": { "201": { "description": "Attachment uploaded" }, "404": { "description": "Document or scoped comment not found", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "error_code": { "type": "string", "example": "collaboration_document_not_found" } }, "type": "object" } } } }, "409": { "description": "Duplicate attachment ID", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "error_code": { "type": "string", "example": "attachment_already_exists" } }, "type": "object" } } } }, "422": { "description": "Laravel field validation or domain type/size/name error", "content": { "application/json": { "schema": { "oneOf": [ { "required": [ "message", "errors" ], "properties": { "message": { "type": "string" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" }, { "required": [ "title", "status", "error_code" ], "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "error_code": { "type": "string", "example": "unsupported_attachment_type" } }, "type": "object" } ] } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Missing permission or comment not authored by actor", "content": { "application/json": { "schema": { "oneOf": [ { "properties": { "message": { "type": "string" } }, "type": "object" }, { "properties": { "title": { "type": "string" }, "status": { "type": "integer", "example": 403 }, "error_code": { "type": "string", "example": "comment_not_authored_by_actor" } }, "type": "object" } ] } } } }, "413": { "description": "Request entity too large (PHP post_max_size)" }, "503": { "description": "Attachment storage configuration, connection or write failed; no attachment metadata was stored, the client id stays free (error_code attachment_storage_unavailable)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachmentStorageUnavailableProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/contracts/{documentId}/attachments": { "get": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "List attachments on a purchase contract (Pago)", "description": "Returns every non-deleted attachment on the purchase contract (Pago) ordered by created_at ascending. No download URLs — use the download endpoint. `can_delete` is computed for the authenticated actor.", "operationId": "5a71ddbeddf22eac404b7040c6d22ece", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Attachment list", "content": { "application/json": { "schema": { "properties": { "items": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "comment_id": { "type": "string", "format": "uuid", "nullable": true }, "original_name": { "type": "string" }, "mime_type": { "type": "string" }, "size_bytes": { "type": "integer" }, "uploaded_by": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "can_delete": { "type": "boolean" } }, "type": "object" } } }, "type": "object" } } } }, "404": { "description": "Document or scoped evidence not found", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } } } }, "403": { "description": "Forbidden: permission, membership or evidence ownership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "Upload an attachment on a purchase contract (Contrato)", "description": "Accepts multipart form-data with a client-supplied UUIDv7 id and a file. Allowed types: pdf, jpg, jpeg, png, webp, xlsx, csv, docx. Max 15 MB. Duplicate ids answer 409.", "operationId": "5bb447a3dc53ba7cc6def1db3041b7d6", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "id", "file" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "0190b7a0-1111-7222-8333-444455556666" }, "comment_id": { "description": "Optional existing comment authored by the uploading user on this document", "type": "string", "format": "uuid", "nullable": true }, "file": { "description": "Attachment file (pdf/jpg/jpeg/png/webp/xlsx/csv/docx), max 15 MB", "type": "string", "format": "binary" } }, "type": "object" } } } }, "responses": { "201": { "description": "Attachment uploaded" }, "404": { "description": "Document or scoped evidence not found", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } ] } } } }, "409": { "description": "Duplicate attachment ID", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "error_code": { "type": "string", "example": "attachment_already_exists" } }, "type": "object" } } } }, "422": { "description": "Request validation or domain validation error", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractValidationError" } ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } } } }, "403": { "description": "Forbidden: permission, membership or evidence ownership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } ] } } } }, "413": { "description": "Request entity too large (PHP post_max_size)" }, "503": { "description": "Attachment storage configuration, connection or write failed; no attachment metadata was stored, the client id stays free (error_code attachment_storage_unavailable)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachmentStorageUnavailableProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/contract-activations/{documentId}/attachments": { "get": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "List attachments on a purchase contract activation (Pago)", "description": "Returns every non-deleted attachment on the purchase contract activation (Pago) ordered by created_at ascending. No download URLs — use the download endpoint. `can_delete` is computed for the authenticated actor.", "operationId": "2d0d9369e4071413d4c9386e92158931", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Attachment list", "content": { "application/json": { "schema": { "properties": { "items": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "comment_id": { "type": "string", "format": "uuid", "nullable": true }, "original_name": { "type": "string" }, "mime_type": { "type": "string" }, "size_bytes": { "type": "integer" }, "uploaded_by": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "can_delete": { "type": "boolean" } }, "type": "object" } } }, "type": "object" } } } }, "404": { "description": "Document or scoped evidence not found", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } } } }, "403": { "description": "Forbidden: permission, membership or evidence ownership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "Upload an attachment on a purchase contract activation (Activación)", "description": "Accepts multipart form-data with a client-supplied UUIDv7 id and a file. Allowed types: pdf, jpg, jpeg, png, webp, xlsx, csv, docx. Max 15 MB. Duplicate ids answer 409.", "operationId": "adae6e348fe8eb5e676094c8eb7c2c0a", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "id", "file" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "0190b7a0-1111-7222-8333-444455556666" }, "comment_id": { "description": "Optional existing comment authored by the uploading user on this document", "type": "string", "format": "uuid", "nullable": true }, "file": { "description": "Attachment file (pdf/jpg/jpeg/png/webp/xlsx/csv/docx), max 15 MB", "type": "string", "format": "binary" } }, "type": "object" } } } }, "responses": { "201": { "description": "Attachment uploaded" }, "404": { "description": "Document or scoped evidence not found", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } ] } } } }, "409": { "description": "Duplicate attachment ID", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "error_code": { "type": "string", "example": "attachment_already_exists" } }, "type": "object" } } } }, "422": { "description": "Request validation or domain validation error", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractValidationError" } ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } } } }, "403": { "description": "Forbidden: permission, membership or evidence ownership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } ] } } } }, "413": { "description": "Request entity too large (PHP post_max_size)" }, "503": { "description": "Attachment storage configuration, connection or write failed; no attachment metadata was stored, the client id stays free (error_code attachment_storage_unavailable)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachmentStorageUnavailableProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/contract-addenda/{documentId}/attachments": { "get": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "List attachments on a purchase contract activation (Pago)", "description": "Returns every non-deleted attachment on the purchase contract activation (Pago) ordered by created_at ascending. No download URLs — use the download endpoint. `can_delete` is computed for the authenticated actor.", "operationId": "ed8f21a71ee94112eac9769086649a05", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Attachment list", "content": { "application/json": { "schema": { "properties": { "items": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "comment_id": { "type": "string", "format": "uuid", "nullable": true }, "original_name": { "type": "string" }, "mime_type": { "type": "string" }, "size_bytes": { "type": "integer" }, "uploaded_by": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "can_delete": { "type": "boolean" } }, "type": "object" } } }, "type": "object" } } } }, "404": { "description": "Document or scoped evidence not found", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } } } }, "403": { "description": "Forbidden: permission, membership or evidence ownership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "Upload an attachment on a purchase contract activation (Activación)", "description": "Accepts multipart form-data with a client-supplied UUIDv7 id and a file. Allowed types: pdf, jpg, jpeg, png, webp, xlsx, csv, docx. Max 15 MB. Duplicate ids answer 409.", "operationId": "0bb7267aaff2abfe39e414430025c804", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "id", "file" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "0190b7a0-1111-7222-8333-444455556666" }, "comment_id": { "description": "Optional existing comment authored by the uploading user on this document", "type": "string", "format": "uuid", "nullable": true }, "file": { "description": "Attachment file (pdf/jpg/jpeg/png/webp/xlsx/csv/docx), max 15 MB", "type": "string", "format": "binary" } }, "type": "object" } } } }, "responses": { "201": { "description": "Attachment uploaded" }, "404": { "description": "Document or scoped evidence not found", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } ] } } } }, "409": { "description": "Duplicate attachment ID", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "error_code": { "type": "string", "example": "attachment_already_exists" } }, "type": "object" } } } }, "422": { "description": "Request validation or domain validation error", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractValidationError" } ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } } } }, "403": { "description": "Forbidden: permission, membership or evidence ownership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } ] } } } }, "413": { "description": "Request entity too large (PHP post_max_size)" }, "503": { "description": "Attachment storage configuration, connection or write failed; no attachment metadata was stored, the client id stays free (error_code attachment_storage_unavailable)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachmentStorageUnavailableProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/contract-deactivations/{documentId}/attachments": { "get": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "List attachments on a purchase contract activation (Pago)", "description": "Returns every non-deleted attachment on the purchase contract activation (Pago) ordered by created_at ascending. No download URLs — use the download endpoint. `can_delete` is computed for the authenticated actor.", "operationId": "ec0df852197c63091fa35c18cc2f6c5d", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Attachment list", "content": { "application/json": { "schema": { "properties": { "items": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "comment_id": { "type": "string", "format": "uuid", "nullable": true }, "original_name": { "type": "string" }, "mime_type": { "type": "string" }, "size_bytes": { "type": "integer" }, "uploaded_by": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "can_delete": { "type": "boolean" } }, "type": "object" } } }, "type": "object" } } } }, "404": { "description": "Document or scoped evidence not found", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } } } }, "403": { "description": "Forbidden: permission, membership or evidence ownership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "Upload an attachment on a purchase contract activation (Activación)", "description": "Accepts multipart form-data with a client-supplied UUIDv7 id and a file. Allowed types: pdf, jpg, jpeg, png, webp, xlsx, csv, docx. Max 15 MB. Duplicate ids answer 409.", "operationId": "414af8dd4fba1a8f2e4708c364a3171d", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "id", "file" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "0190b7a0-1111-7222-8333-444455556666" }, "comment_id": { "description": "Optional existing comment authored by the uploading user on this document", "type": "string", "format": "uuid", "nullable": true }, "file": { "description": "Attachment file (pdf/jpg/jpeg/png/webp/xlsx/csv/docx), max 15 MB", "type": "string", "format": "binary" } }, "type": "object" } } } }, "responses": { "201": { "description": "Attachment uploaded" }, "404": { "description": "Document or scoped evidence not found", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } ] } } } }, "409": { "description": "Duplicate attachment ID", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "error_code": { "type": "string", "example": "attachment_already_exists" } }, "type": "object" } } } }, "422": { "description": "Request validation or domain validation error", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractValidationError" } ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } } } }, "403": { "description": "Forbidden: permission, membership or evidence ownership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } ] } } } }, "413": { "description": "Request entity too large (PHP post_max_size)" }, "503": { "description": "Attachment storage configuration, connection or write failed; no attachment metadata was stored, the client id stays free (error_code attachment_storage_unavailable)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachmentStorageUnavailableProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/contracts/{contractId}/attachments": { "get": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "List attachments on a sales contract (Pago)", "description": "Returns every non-deleted attachment on the sales contract (Pago) ordered by created_at ascending. No download URLs — use the download endpoint. `can_delete` is computed for the authenticated actor.", "operationId": "ff900af9e64a0416845ceb73c7a84fe6", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "contractId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Attachment list", "content": { "application/json": { "schema": { "properties": { "items": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "comment_id": { "type": "string", "format": "uuid", "nullable": true }, "original_name": { "type": "string" }, "mime_type": { "type": "string" }, "size_bytes": { "type": "integer" }, "uploaded_by": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "can_delete": { "type": "boolean" } }, "type": "object" } } }, "type": "object" } } } }, "404": { "description": "Document or scoped evidence not found", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractProblemResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } } } }, "403": { "description": "Forbidden: permission, membership or evidence ownership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractProblemResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareForbiddenResponse" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "Upload an attachment on a sales contract (Contrato)", "description": "Accepts multipart form-data with a client-supplied UUIDv7 id and a file. Allowed types: pdf, jpg, jpeg, png, webp, xlsx, csv, docx. Max 15 MB. Duplicate ids answer 409.", "operationId": "e61e7d22f49323537e33b5965acbc828", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "contractId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "id", "file" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "0190b7a0-1111-7222-8333-444455556666" }, "comment_id": { "description": "Optional existing comment authored by the uploading user on this document", "type": "string", "format": "uuid", "nullable": true }, "file": { "description": "Attachment file (pdf/jpg/jpeg/png/webp/xlsx/csv/docx), max 15 MB", "type": "string", "format": "binary" } }, "type": "object" } } } }, "responses": { "201": { "description": "Attachment uploaded" }, "404": { "description": "Document or scoped evidence not found", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractProblemResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } ] } } } }, "409": { "description": "Duplicate attachment ID", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "error_code": { "type": "string", "example": "attachment_already_exists" } }, "type": "object" } } } }, "422": { "description": "Request validation or domain validation error", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractProblemResponse" }, { "$ref": "#/components/schemas/ContractRequestValidationResponse" } ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } } } }, "403": { "description": "Forbidden: permission, membership or evidence ownership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractProblemResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareForbiddenResponse" } ] } } } }, "413": { "description": "Request entity too large (PHP post_max_size)" }, "503": { "description": "Attachment storage configuration, connection or write failed; no attachment metadata was stored, the client id stays free (error_code attachment_storage_unavailable)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachmentStorageUnavailableProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/contract-activations/{activationId}/attachments": { "get": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "List attachments on a sales contract activation", "description": "Returns every non-deleted attachment on the sales contract activation ordered by created_at ascending. No download URLs — use the download endpoint. `can_delete` is computed for the authenticated actor.", "operationId": "e7c7d6ab05ff251dd192f7c599cfbfda", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "activationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Attachment list", "content": { "application/json": { "schema": { "properties": { "items": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "comment_id": { "type": "string", "format": "uuid", "nullable": true }, "original_name": { "type": "string" }, "mime_type": { "type": "string" }, "size_bytes": { "type": "integer" }, "uploaded_by": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "can_delete": { "type": "boolean" } }, "type": "object" } } }, "type": "object" } } } }, "404": { "description": "Document or scoped evidence not found", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractProblemResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } } } }, "403": { "description": "Forbidden: permission, membership or evidence ownership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractProblemResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareForbiddenResponse" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "Upload an attachment on a sales contract activation", "description": "Accepts multipart form-data with a client-supplied UUIDv7 id and a file. Allowed types: pdf, jpg, jpeg, png, webp, xlsx, csv, docx. Max 15 MB. Duplicate ids answer 409.", "operationId": "550144213539ac7f128120e055401a10", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "activationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "id", "file" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "0190b7a0-1111-7222-8333-444455556666" }, "comment_id": { "description": "Optional existing comment authored by the uploading user on this document", "type": "string", "format": "uuid", "nullable": true }, "file": { "description": "Attachment file (pdf/jpg/jpeg/png/webp/xlsx/csv/docx), max 15 MB", "type": "string", "format": "binary" } }, "type": "object" } } } }, "responses": { "201": { "description": "Attachment uploaded" }, "404": { "description": "Document or scoped evidence not found", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractProblemResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } ] } } } }, "409": { "description": "Duplicate attachment ID", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "error_code": { "type": "string", "example": "attachment_already_exists" } }, "type": "object" } } } }, "422": { "description": "Request validation or domain validation error", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractProblemResponse" }, { "$ref": "#/components/schemas/ContractRequestValidationResponse" } ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } } } }, "403": { "description": "Forbidden: permission, membership or evidence ownership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractProblemResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareForbiddenResponse" } ] } } } }, "413": { "description": "Request entity too large (PHP post_max_size)" }, "503": { "description": "Attachment storage configuration, connection or write failed; no attachment metadata was stored, the client id stays free (error_code attachment_storage_unavailable)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachmentStorageUnavailableProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/contract-deactivations/{deactivationId}/attachments": { "get": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "List attachments on a sales contract deactivation", "description": "Returns every non-deleted attachment on the sales contract deactivation ordered by created_at ascending. No download URLs — use the download endpoint. `can_delete` is computed for the authenticated actor.", "operationId": "89e45c0610adbb9f45a6e287a71da4c8", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "deactivationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Attachment list", "content": { "application/json": { "schema": { "properties": { "items": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "comment_id": { "type": "string", "format": "uuid", "nullable": true }, "original_name": { "type": "string" }, "mime_type": { "type": "string" }, "size_bytes": { "type": "integer" }, "uploaded_by": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "can_delete": { "type": "boolean" } }, "type": "object" } } }, "type": "object" } } } }, "404": { "description": "Document or scoped evidence not found", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractProblemResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } } } }, "403": { "description": "Forbidden: permission, membership or evidence ownership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractProblemResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareForbiddenResponse" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "Upload an attachment on a sales contract deactivation", "description": "Accepts multipart form-data with a client-supplied UUIDv7 id and a file. Allowed types: pdf, jpg, jpeg, png, webp, xlsx, csv, docx. Max 15 MB. Duplicate ids answer 409.", "operationId": "5fdd8f0e2e30ea4c60791161aff998fb", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "deactivationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "id", "file" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "0190b7a0-1111-7222-8333-444455556666" }, "comment_id": { "description": "Optional existing comment authored by the uploading user on this document", "type": "string", "format": "uuid", "nullable": true }, "file": { "description": "Attachment file (pdf/jpg/jpeg/png/webp/xlsx/csv/docx), max 15 MB", "type": "string", "format": "binary" } }, "type": "object" } } } }, "responses": { "201": { "description": "Attachment uploaded" }, "404": { "description": "Document or scoped evidence not found", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractProblemResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } ] } } } }, "409": { "description": "Duplicate attachment ID", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "error_code": { "type": "string", "example": "attachment_already_exists" } }, "type": "object" } } } }, "422": { "description": "Request validation or domain validation error", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractProblemResponse" }, { "$ref": "#/components/schemas/ContractRequestValidationResponse" } ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } } } }, "403": { "description": "Forbidden: permission, membership or evidence ownership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractProblemResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareForbiddenResponse" } ] } } } }, "413": { "description": "Request entity too large (PHP post_max_size)" }, "503": { "description": "Attachment storage configuration, connection or write failed; no attachment metadata was stored, the client id stays free (error_code attachment_storage_unavailable)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachmentStorageUnavailableProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/potential-customers/{potentialCustomerId}/attachments": { "get": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "List attachments on a sales contract deactivation", "description": "Returns every non-deleted attachment on the sales contract deactivation ordered by created_at ascending. No download URLs — use the download endpoint. `can_delete` is computed for the authenticated actor.", "operationId": "254b9a3c7caa59b6f20494b745bd9985", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "potentialCustomerId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Attachment list", "content": { "application/json": { "schema": { "properties": { "items": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "comment_id": { "type": "string", "format": "uuid", "nullable": true }, "original_name": { "type": "string" }, "mime_type": { "type": "string" }, "size_bytes": { "type": "integer" }, "uploaded_by": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "can_delete": { "type": "boolean" } }, "type": "object" } } }, "type": "object" } } } }, "404": { "description": "Document or scoped evidence not found", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractProblemResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } } } }, "403": { "description": "Forbidden: permission, membership or evidence ownership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractProblemResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareForbiddenResponse" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "Upload an attachment on a sales contract deactivation", "description": "Accepts multipart form-data with a client-supplied UUIDv7 id and a file. Allowed types: pdf, jpg, jpeg, png, webp, xlsx, csv, docx. Max 15 MB. Duplicate ids answer 409.", "operationId": "abee0322c2722d36f8478f1c2c1e0a5c", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "potentialCustomerId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "id", "file" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "0190b7a0-1111-7222-8333-444455556666" }, "comment_id": { "description": "Optional existing comment authored by the uploading user on this document", "type": "string", "format": "uuid", "nullable": true }, "file": { "description": "Attachment file (pdf/jpg/jpeg/png/webp/xlsx/csv/docx), max 15 MB", "type": "string", "format": "binary" } }, "type": "object" } } } }, "responses": { "201": { "description": "Attachment uploaded" }, "404": { "description": "Document or scoped evidence not found", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractProblemResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } ] } } } }, "409": { "description": "Duplicate attachment ID", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "error_code": { "type": "string", "example": "attachment_already_exists" } }, "type": "object" } } } }, "422": { "description": "Request validation or domain validation error", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractProblemResponse" }, { "$ref": "#/components/schemas/ContractRequestValidationResponse" } ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } } } }, "403": { "description": "Forbidden: permission, membership or evidence ownership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractProblemResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareForbiddenResponse" } ] } } } }, "413": { "description": "Request entity too large (PHP post_max_size)" }, "503": { "description": "Attachment storage configuration, connection or write failed; no attachment metadata was stored, the client id stays free (error_code attachment_storage_unavailable)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachmentStorageUnavailableProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/transfers/{documentId}/attachments": { "get": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "List attachments on an inventory transfer (Traslado de inventario)", "description": "Returns every non-deleted attachment on the Traslado de inventario ordered by created_at ascending. No download URLs — use the download endpoint. `can_delete` is computed for the authenticated actor.", "operationId": "71918a31fe399188cbc69bf3694e6492", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Attachment list", "content": { "application/json": { "schema": { "properties": { "items": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "comment_id": { "type": "string", "format": "uuid", "nullable": true }, "original_name": { "type": "string" }, "mime_type": { "type": "string" }, "size_bytes": { "type": "integer" }, "uploaded_by": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "can_delete": { "type": "boolean" } }, "type": "object" } } }, "type": "object" } } } }, "404": { "description": "Document not found", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "error_code": { "type": "string", "example": "collaboration_document_not_found" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "Upload an attachment on an inventory transfer (Traslado de inventario)", "description": "Accepts multipart form-data with a client-supplied UUIDv7 id and a file. Allowed types: pdf, jpg, jpeg, png, webp, xlsx, csv, docx. Max 15 MB. Duplicate ids answer 409.", "operationId": "958ea22241178391bbf6aee7aef8118b", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "id", "file" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "0190b7a0-1111-7222-8333-444455556666" }, "comment_id": { "description": "Optional existing comment authored by the uploading user on this document", "type": "string", "format": "uuid", "nullable": true }, "file": { "description": "Attachment file (pdf/jpg/jpeg/png/webp/xlsx/csv/docx), max 15 MB", "type": "string", "format": "binary" } }, "type": "object" } } } }, "responses": { "201": { "description": "Attachment uploaded" }, "404": { "description": "Document or scoped comment not found", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "error_code": { "type": "string", "example": "collaboration_document_not_found" } }, "type": "object" } } } }, "409": { "description": "Duplicate attachment ID", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "error_code": { "type": "string", "example": "attachment_already_exists" } }, "type": "object" } } } }, "422": { "description": "Laravel field validation or domain type/size/name error", "content": { "application/json": { "schema": { "oneOf": [ { "required": [ "message", "errors" ], "properties": { "message": { "type": "string" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" }, { "required": [ "title", "status", "error_code" ], "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "error_code": { "type": "string", "example": "unsupported_attachment_type" } }, "type": "object" } ] } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Missing permission or comment not authored by actor", "content": { "application/json": { "schema": { "oneOf": [ { "properties": { "message": { "type": "string" } }, "type": "object" }, { "properties": { "title": { "type": "string" }, "status": { "type": "integer", "example": 403 }, "error_code": { "type": "string", "example": "comment_not_authored_by_actor" } }, "type": "object" } ] } } } }, "413": { "description": "Request entity too large (PHP post_max_size)" }, "503": { "description": "Attachment storage configuration, connection or write failed; no attachment metadata was stored, the client id stays free (error_code attachment_storage_unavailable)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachmentStorageUnavailableProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/treasury/transfers/{documentId}/attachments": { "get": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "List attachments on a treasury transfer (transferencia entre cuentas propias)", "description": "Returns every non-deleted attachment on the transferencia entre cuentas propias ordered by created_at ascending. No download URLs — use the download endpoint. `can_delete` is computed for the authenticated actor. Requires `backoffice.treasury.treasury-transfers.view`.", "operationId": "31490657eb9f35547e9239fa713deeb6", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Attachment list", "content": { "application/json": { "schema": { "properties": { "items": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "comment_id": { "type": "string", "format": "uuid", "nullable": true }, "original_name": { "type": "string" }, "mime_type": { "type": "string" }, "size_bytes": { "type": "integer" }, "uploaded_by": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "can_delete": { "type": "boolean" } }, "type": "object" } } }, "type": "object" } } } }, "404": { "description": "Document not found", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "error_code": { "type": "string", "example": "collaboration_document_not_found" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "Upload an attachment on a treasury transfer (transferencia entre cuentas propias)", "description": "Accepts multipart form-data with a client-supplied UUIDv7 id and a file. Allowed types: pdf, jpg, jpeg, png, webp, xlsx, csv, docx. Max 15 MB. Duplicate ids answer 409. Requires `backoffice.treasury.treasury-transfers.view`.", "operationId": "434811295c1cd926ce7a6ad3a701f4d3", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "id", "file" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "0190b7a0-1111-7222-8333-444455556666" }, "comment_id": { "description": "Optional existing comment authored by the uploading user on this document", "type": "string", "format": "uuid", "nullable": true }, "file": { "description": "Attachment file (pdf/jpg/jpeg/png/webp/xlsx/csv/docx), max 15 MB", "type": "string", "format": "binary" } }, "type": "object" } } } }, "responses": { "201": { "description": "Attachment uploaded" }, "404": { "description": "Document or scoped comment not found", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "error_code": { "type": "string", "example": "collaboration_document_not_found" } }, "type": "object" } } } }, "409": { "description": "Duplicate attachment ID", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "error_code": { "type": "string", "example": "attachment_already_exists" } }, "type": "object" } } } }, "422": { "description": "Laravel field validation or domain type/size/name error", "content": { "application/json": { "schema": { "oneOf": [ { "required": [ "message", "errors" ], "properties": { "message": { "type": "string" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" }, { "required": [ "title", "status", "error_code" ], "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "error_code": { "type": "string", "example": "unsupported_attachment_type" } }, "type": "object" } ] } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Missing permission or comment not authored by actor", "content": { "application/json": { "schema": { "oneOf": [ { "properties": { "message": { "type": "string" } }, "type": "object" }, { "properties": { "title": { "type": "string" }, "status": { "type": "integer", "example": 403 }, "error_code": { "type": "string", "example": "comment_not_authored_by_actor" } }, "type": "object" } ] } } } }, "413": { "description": "Request entity too large (PHP post_max_size)" }, "503": { "description": "Attachment storage configuration, connection or write failed; no attachment metadata was stored, the client id stays free (error_code attachment_storage_unavailable)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachmentStorageUnavailableProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/dispatches/{documentId}/attachments": { "get": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "List attachments on an inventory dispatch (Despacho de inventario)", "description": "Returns every non-deleted attachment on the Despacho de inventario ordered by created_at ascending. No download URLs — use the download endpoint. `can_delete` is computed for the authenticated actor.", "operationId": "9efb606b1a4541ac146a694f4032cde9", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Attachment list", "content": { "application/json": { "schema": { "properties": { "items": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "comment_id": { "type": "string", "format": "uuid", "nullable": true }, "original_name": { "type": "string" }, "mime_type": { "type": "string" }, "size_bytes": { "type": "integer" }, "uploaded_by": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "can_delete": { "type": "boolean" } }, "type": "object" } } }, "type": "object" } } } }, "404": { "description": "HTTP 404; document, child and company scope are enforced", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/InventoryDispatchProblem" }, { "$ref": "#/components/schemas/InventoryDispatchUnauthenticated" } ] } } } }, "401": { "description": "HTTP 401; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryDispatchUnauthenticated" } } } }, "403": { "description": "HTTP 403; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryDispatchForbidden" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "Upload an attachment on an inventory dispatch (Despacho de inventario)", "description": "Accepts multipart form-data with a client-supplied UUIDv7 id and a file. Allowed types: pdf, jpg, jpeg, png, webp, xlsx, csv, docx. Max 15 MB. Duplicate ids answer 409.", "operationId": "f5adfc5e536b6ecb818cfe42ce4fb011", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "id", "file" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "0190b7a0-1111-7222-8333-444455556666" }, "comment_id": { "description": "Optional existing comment authored by the uploading user on this document", "type": "string", "format": "uuid", "nullable": true }, "file": { "description": "Attachment file (pdf/jpg/jpeg/png/webp/xlsx/csv/docx), max 15 MB", "type": "string", "format": "binary" } }, "type": "object" } } } }, "responses": { "201": { "description": "Empty JSON object acknowledgement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryDispatchAcknowledgement" } } } }, "404": { "description": "HTTP 404; document, child and company scope are enforced", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/InventoryDispatchProblem" }, { "$ref": "#/components/schemas/InventoryDispatchUnauthenticated" } ] } } } }, "409": { "description": "HTTP 409; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryDispatchProblem" } } } }, "422": { "description": "HTTP 422; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryDispatchProblem" } } } }, "401": { "description": "HTTP 401; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryDispatchUnauthenticated" } } } }, "403": { "description": "HTTP 403; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryDispatchForbidden" } } } }, "413": { "description": "Request entity too large (PHP post_max_size)" }, "503": { "description": "Attachment storage configuration, connection or write failed; no attachment metadata was stored, the client id stays free (error_code attachment_storage_unavailable)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachmentStorageUnavailableProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/entries/{documentId}/attachments": { "get": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "List attachments on an inventory entry (Entrada de inventario)", "description": "Returns every non-deleted attachment on the Entrada de inventario ordered by created_at ascending. No download URLs — use the download endpoint. `can_delete` is computed for the authenticated actor.", "operationId": "f98c2482b363966a8653fdc00ebfb88c", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Attachment list", "content": { "application/json": { "schema": { "properties": { "items": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "comment_id": { "type": "string", "format": "uuid", "nullable": true }, "original_name": { "type": "string" }, "mime_type": { "type": "string" }, "size_bytes": { "type": "integer" }, "uploaded_by": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "can_delete": { "type": "boolean" } }, "type": "object" } } }, "type": "object" } } } }, "404": { "description": "HTTP 404; document, child and company scope are enforced", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/InventoryEntryProblem" }, { "$ref": "#/components/schemas/InventoryEntryUnauthenticated" } ] } } } }, "401": { "description": "HTTP 401; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryEntryUnauthenticated" } } } }, "403": { "description": "HTTP 403; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryEntryForbidden" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "Upload an attachment on an inventory entry (Entrada de inventario)", "description": "Accepts multipart form-data with a client-supplied UUIDv7 id and a file. Allowed types: pdf, jpg, jpeg, png, webp, xlsx, csv, docx. Max 15 MB. Duplicate ids answer 409.", "operationId": "24fcc6309e1385a8d79029d928d31e39", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "id", "file" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "0190b7a0-1111-7222-8333-444455556666" }, "comment_id": { "description": "Optional existing comment authored by the uploading user on this document", "type": "string", "format": "uuid", "nullable": true }, "file": { "description": "Attachment file (pdf/jpg/jpeg/png/webp/xlsx/csv/docx), max 15 MB", "type": "string", "format": "binary" } }, "type": "object" } } } }, "responses": { "201": { "description": "Empty JSON object acknowledgement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryEntryAcknowledgement" } } } }, "404": { "description": "HTTP 404; document, child and company scope are enforced", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/InventoryEntryProblem" }, { "$ref": "#/components/schemas/InventoryEntryUnauthenticated" } ] } } } }, "409": { "description": "HTTP 409; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryEntryProblem" } } } }, "422": { "description": "HTTP 422; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryEntryProblem" } } } }, "401": { "description": "HTTP 401; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryEntryUnauthenticated" } } } }, "403": { "description": "HTTP 403; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryEntryForbidden" } } } }, "413": { "description": "Request entity too large (PHP post_max_size)" }, "503": { "description": "Attachment storage configuration, connection or write failed; no attachment metadata was stored, the client id stays free (error_code attachment_storage_unavailable)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachmentStorageUnavailableProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/transformations/{documentId}/attachments": { "get": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "List attachments on a transformation (Transformación de ítems)", "description": "Returns every non-deleted attachment on the Transformación de ítems ordered by created_at ascending. No download URLs — use the download endpoint. `can_delete` is computed for the authenticated actor.", "operationId": "9160cf0ee3f898eb75e708da3710cb5e", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Attachment list", "content": { "application/json": { "schema": { "properties": { "items": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "comment_id": { "type": "string", "format": "uuid", "nullable": true }, "original_name": { "type": "string" }, "mime_type": { "type": "string" }, "size_bytes": { "type": "integer" }, "uploaded_by": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "can_delete": { "type": "boolean" } }, "type": "object" } } }, "type": "object" } } } }, "404": { "description": "HTTP 404; document, child and company scope are enforced", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/TransformationProblem" }, { "$ref": "#/components/schemas/TransformationUnauthenticated" } ] } } } }, "401": { "description": "HTTP 401; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransformationUnauthenticated" } } } }, "403": { "description": "HTTP 403; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransformationForbidden" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "Upload an attachment on a transformation (Transformación de ítems)", "description": "Accepts multipart form-data with a client-supplied UUIDv7 id and a file. Allowed types: pdf, jpg, jpeg, png, webp, xlsx, csv, docx. Max 15 MB. Duplicate ids answer 409.", "operationId": "0b2bb53ddd19775813d630091e7364d5", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "id", "file" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "0190b7a0-1111-7222-8333-444455556666" }, "comment_id": { "description": "Optional existing comment authored by the uploading user on this document", "type": "string", "format": "uuid", "nullable": true }, "file": { "description": "Attachment file (pdf/jpg/jpeg/png/webp/xlsx/csv/docx), max 15 MB", "type": "string", "format": "binary" } }, "type": "object" } } } }, "responses": { "201": { "description": "Empty JSON object acknowledgement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransformationAcknowledgement" } } } }, "404": { "description": "HTTP 404; document, child and company scope are enforced", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/TransformationProblem" }, { "$ref": "#/components/schemas/TransformationUnauthenticated" } ] } } } }, "409": { "description": "HTTP 409; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransformationProblem" } } } }, "422": { "description": "HTTP 422; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransformationProblem" } } } }, "401": { "description": "HTTP 401; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransformationUnauthenticated" } } } }, "403": { "description": "HTTP 403; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransformationForbidden" } } } }, "413": { "description": "Request entity too large (PHP post_max_size)" }, "503": { "description": "Attachment storage configuration, connection or write failed; no attachment metadata was stored, the client id stays free (error_code attachment_storage_unavailable)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachmentStorageUnavailableProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/adjustments/{documentId}/attachments": { "get": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "List attachments on an inventory adjustment (Ajuste de inventario)", "description": "Returns every non-deleted attachment on the Ajuste de inventario ordered by created_at ascending. No download URLs — use the download endpoint. `can_delete` is computed for the authenticated actor.", "operationId": "ba4828251999f465686abf20c938b4b9", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Attachment list", "content": { "application/json": { "schema": { "properties": { "items": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "comment_id": { "type": "string", "format": "uuid", "nullable": true }, "original_name": { "type": "string" }, "mime_type": { "type": "string" }, "size_bytes": { "type": "integer" }, "uploaded_by": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "can_delete": { "type": "boolean" } }, "type": "object" } } }, "type": "object" } } } }, "404": { "description": "HTTP 404; document, child and company scope are enforced", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/AdjustmentProblem" }, { "$ref": "#/components/schemas/AdjustmentUnauthenticated" } ] } } } }, "401": { "description": "HTTP 401; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdjustmentUnauthenticated" } } } }, "403": { "description": "HTTP 403; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdjustmentForbidden" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "Upload an attachment on an inventory adjustment (Ajuste de inventario)", "description": "Accepts multipart form-data with a client-supplied UUIDv7 id and a file. Allowed types: pdf, jpg, jpeg, png, webp, xlsx, csv, docx. Max 15 MB. Duplicate ids answer 409.", "operationId": "0fada0fb3a37578fe13a9fcdb34701f5", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "id", "file" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "0190b7a0-1111-7222-8333-444455556666" }, "comment_id": { "description": "Optional existing comment authored by the uploading user on this document", "type": "string", "format": "uuid", "nullable": true }, "file": { "description": "Attachment file (pdf/jpg/jpeg/png/webp/xlsx/csv/docx), max 15 MB", "type": "string", "format": "binary" } }, "type": "object" } } } }, "responses": { "201": { "description": "Empty JSON object acknowledgement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdjustmentAcknowledgement" } } } }, "404": { "description": "HTTP 404; document, child and company scope are enforced", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/AdjustmentProblem" }, { "$ref": "#/components/schemas/AdjustmentUnauthenticated" } ] } } } }, "409": { "description": "HTTP 409; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdjustmentProblem" } } } }, "422": { "description": "HTTP 422; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdjustmentProblem" } } } }, "401": { "description": "HTTP 401; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdjustmentUnauthenticated" } } } }, "403": { "description": "HTTP 403; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdjustmentForbidden" } } } }, "413": { "description": "Request entity too large (PHP post_max_size)" }, "503": { "description": "Attachment storage configuration, connection or write failed; no attachment metadata was stored, the client id stays free (error_code attachment_storage_unavailable)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachmentStorageUnavailableProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/credit-notes/{documentId}/attachments": { "get": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "List attachments on a supplier nota de crédito de proveedor", "description": "Requires `backoffice.purchases.credit-notes.view`. Returns every non-deleted attachment ordered by created_at ascending. No download URLs — use the download endpoint. `can_delete` is computed for the authenticated actor.", "operationId": "68a698b436eef7813bdb9cb1558f7761", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Attachment list", "content": { "application/json": { "schema": { "properties": { "items": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "comment_id": { "type": "string", "format": "uuid", "nullable": true }, "original_name": { "type": "string" }, "mime_type": { "type": "string" }, "size_bytes": { "type": "integer" }, "uploaded_by": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "can_delete": { "type": "boolean" } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks backoffice.purchases.credit-notes.view" }, "404": { "description": "Document not found" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "Upload an attachment on a supplier nota de crédito de proveedor", "description": "Requires `backoffice.purchases.credit-notes.view`. Accepts multipart form-data with a client-supplied UUIDv7 id and a file. Allowed types: pdf, jpg, jpeg, png, webp, xlsx, csv, docx. Max 15 MB. Duplicate ids answer 409.", "operationId": "fff2360223edb8d33c4fe8ccad459f23", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "id", "file" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "0190b7a0-1111-7222-8333-444455556666" }, "comment_id": { "description": "Optional existing comment authored by the uploading user on this document", "type": "string", "format": "uuid", "nullable": true }, "file": { "description": "Attachment file (pdf/jpg/jpeg/png/webp/xlsx/csv/docx), max 15 MB", "type": "string", "format": "binary" } }, "type": "object" } } } }, "responses": { "201": { "description": "Attachment uploaded" }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks backoffice.purchases.credit-notes.view" }, "404": { "description": "Document not found" }, "409": { "description": "Duplicate attachment ID" }, "413": { "description": "Request entity too large (PHP post_max_size)" }, "422": { "description": "Validation error" }, "503": { "description": "Attachment storage unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachmentStorageUnavailableProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/debit-notes/{documentId}/attachments": { "get": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "List attachments on a supplier nota de débito de proveedor", "description": "Requires `backoffice.purchases.debit-notes.view`. Returns every non-deleted attachment ordered by created_at ascending. No download URLs — use the download endpoint. `can_delete` is computed for the authenticated actor.", "operationId": "9347804077aa56b228f7388af7e66a2e", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Attachment list", "content": { "application/json": { "schema": { "properties": { "items": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "comment_id": { "type": "string", "format": "uuid", "nullable": true }, "original_name": { "type": "string" }, "mime_type": { "type": "string" }, "size_bytes": { "type": "integer" }, "uploaded_by": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "can_delete": { "type": "boolean" } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks backoffice.purchases.debit-notes.view" }, "404": { "description": "Document not found" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Collaboration - Attachments" ], "summary": "Upload an attachment on a supplier nota de débito de proveedor", "description": "Requires `backoffice.purchases.debit-notes.view`. Accepts multipart form-data with a client-supplied UUIDv7 id and a file. Allowed types: pdf, jpg, jpeg, png, webp, xlsx, csv, docx. Max 15 MB. Duplicate ids answer 409.", "operationId": "6634c2e89848856768232e42c2925d72", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "id", "file" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "0190b7a0-1111-7222-8333-444455556666" }, "comment_id": { "description": "Optional existing comment authored by the uploading user on this document", "type": "string", "format": "uuid", "nullable": true }, "file": { "description": "Attachment file (pdf/jpg/jpeg/png/webp/xlsx/csv/docx), max 15 MB", "type": "string", "format": "binary" } }, "type": "object" } } } }, "responses": { "201": { "description": "Attachment uploaded" }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks backoffice.purchases.debit-notes.view" }, "404": { "description": "Document not found" }, "409": { "description": "Duplicate attachment ID" }, "413": { "description": "Request entity too large (PHP post_max_size)" }, "422": { "description": "Validation error" }, "503": { "description": "Attachment storage unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachmentStorageUnavailableProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/orders/{documentId}/comments/{commentId}": { "put": { "tags": [ "Backoffice - Collaboration - Comments" ], "summary": "Edit a comment on a purchase order (Pedido)", "description": "Author-only edit. Sets edited_at to now.", "operationId": "f2ac89f9b9550848282eea8cda568663", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "commentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "body" ], "properties": { "body": { "description": "Texto plano, incluidos los tokens @[Nombre](user:id); máximo 20 personas mencionadas", "type": "string", "maxLength": 5000 } }, "type": "object" } } } }, "responses": { "200": { "description": "Comment updated" }, "403": { "description": "Actor is not the author", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Forbidden" }, "status": { "type": "integer", "example": 403 }, "error_code": { "type": "string", "example": "comment_not_authored_by_actor" } }, "type": "object" } } } }, "404": { "description": "Document or comment not found", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "error_code": { "type": "string", "example": "comment_not_found" } }, "type": "object" } } } }, "422": { "description": "Validación del texto o las menciones: máximo 5000 caracteres incluidos los tokens, 20 personas y solo miembros con vista; los rechazados se devuelven en rejected_user_ids", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollaborationCommentWriteProblem" } } } }, "401": { "description": "Unauthenticated" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Backoffice - Collaboration - Comments" ], "summary": "Delete a comment on a purchase order (Pedido)", "description": "Hard-deletes the comment. Author or company admin (AuthorizationPolicy::isAdmin) may delete.", "operationId": "86ecd10de5a6c3e26387ed1bb3c864ad", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "commentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Comment deleted" }, "403": { "description": "Actor is not the author and is not an admin", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Forbidden" }, "status": { "type": "integer", "example": 403 }, "error_code": { "type": "string", "example": "comment_not_authored_by_actor" } }, "type": "object" } } } }, "404": { "description": "Document or comment not found", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "error_code": { "type": "string", "example": "comment_not_found" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/purchases-orders/{documentId}/comments/{commentId}": { "put": { "tags": [ "Backoffice - Collaboration - Comments" ], "summary": "Edit a comment on a purchase order (Orden de compra)", "description": "Author-only edit. Sets edited_at to now.", "operationId": "059aac3e5a1e5c17e30a03a6250cd95b", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "commentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "body" ], "properties": { "body": { "description": "Texto plano, incluidos los tokens @[Nombre](user:id); máximo 20 personas mencionadas", "type": "string", "maxLength": 5000 } }, "type": "object" } } } }, "responses": { "200": { "description": "Comment updated" }, "403": { "description": "Actor is not the author", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Forbidden" }, "status": { "type": "integer", "example": 403 }, "error_code": { "type": "string", "example": "comment_not_authored_by_actor" } }, "type": "object" } } } }, "404": { "description": "Document or comment not found", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "error_code": { "type": "string", "example": "comment_not_found" } }, "type": "object" } } } }, "422": { "description": "Validación del texto o las menciones: máximo 5000 caracteres incluidos los tokens, 20 personas y solo miembros con vista; los rechazados se devuelven en rejected_user_ids", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollaborationCommentWriteProblem" } } } }, "401": { "description": "Unauthenticated" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Backoffice - Collaboration - Comments" ], "summary": "Delete a comment on a purchase order (Orden de compra)", "description": "Hard-deletes the comment. Author or company admin (AuthorizationPolicy::isAdmin) may delete.", "operationId": "ce180daf55a53ffe22795e8d195050ab", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "commentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Comment deleted" }, "403": { "description": "Actor is not the author and is not an admin", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Forbidden" }, "status": { "type": "integer", "example": 403 }, "error_code": { "type": "string", "example": "comment_not_authored_by_actor" } }, "type": "object" } } } }, "404": { "description": "Document or comment not found", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "error_code": { "type": "string", "example": "comment_not_found" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/providers/{documentId}/comments/{commentId}": { "put": { "tags": [ "Backoffice - Collaboration - Comments" ], "summary": "Edit a comment on a provider", "description": "Requires `backoffice.purchases.providers.view`. Author-only edit. Sets edited_at to now.", "operationId": "cae7a34b79a683bc93bfe13f3903a60a", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "commentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "body" ], "properties": { "body": { "description": "Texto plano, incluidos los tokens @[Nombre](user:id); máximo 20 personas mencionadas", "type": "string", "maxLength": 5000 } }, "type": "object" } } } }, "responses": { "200": { "description": "Comment updated" }, "403": { "description": "Actor is not the author", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Forbidden" }, "status": { "type": "integer", "example": 403 }, "error_code": { "type": "string", "example": "comment_not_authored_by_actor" } }, "type": "object" } } } }, "404": { "description": "Document or comment not found", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "error_code": { "type": "string", "example": "comment_not_found" } }, "type": "object" } } } }, "422": { "description": "Validación del texto o las menciones: máximo 5000 caracteres incluidos los tokens, 20 personas y solo miembros con vista; los rechazados se devuelven en rejected_user_ids", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollaborationCommentWriteProblem" } } } }, "401": { "description": "Unauthenticated" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Backoffice - Collaboration - Comments" ], "summary": "Delete a comment on a provider", "description": "Requires `backoffice.purchases.providers.view`. Hard-deletes the comment. Author or company admin (AuthorizationPolicy::isAdmin) may delete.", "operationId": "9bbcbbe22d044cb10c2f0193663f1fc1", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "commentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Comment deleted" }, "403": { "description": "Actor is not the author and is not an admin", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Forbidden" }, "status": { "type": "integer", "example": 403 }, "error_code": { "type": "string", "example": "comment_not_authored_by_actor" } }, "type": "object" } } } }, "404": { "description": "Document or comment not found", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "error_code": { "type": "string", "example": "comment_not_found" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/collections/{documentId}/comments/{commentId}": { "put": { "tags": [ "Backoffice - Collaboration - Comments" ], "summary": "Edit an authored collection comment", "description": "Requires collections.view and company membership. The parent Collection and evidence ids must belong to the route company and parent. Comments are plain text. Authors alone edit comments; authors/uploaders or company administrators delete their evidence. A screenshot reports payment evidence and never sets or confirms the informational crediting date.", "operationId": "5bbb9e0583675639a040acf2756f62e4", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "commentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "body" ], "properties": { "body": { "description": "Texto plano, incluidos los tokens @[Nombre](user:id); máximo 20 personas mencionadas", "type": "string", "maxLength": 5000 } }, "type": "object" } } } }, "responses": { "200": { "description": "Edit an authored collection comment" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "oneOf": [ { "required": [ "message" ], "properties": { "message": { "type": "string" } }, "type": "object" } ] } } } }, "403": { "description": "Missing collections.view or company membership; actor cannot edit/delete another user evidence or attach to another user comment", "content": { "application/json": { "schema": { "oneOf": [ { "required": [ "message" ], "properties": { "message": { "type": "string" } }, "type": "object" }, { "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "error_code": { "type": "string", "nullable": true }, "errors": { "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" } ] } } } }, "404": { "description": "Collection, scoped comment or attachment not found; foreign parents and substituted evidence ids are hidden", "content": { "application/json": { "schema": { "oneOf": [ { "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "error_code": { "type": "string", "nullable": true }, "errors": { "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" } ] } } } }, "422": { "description": "Validación del texto o las menciones: máximo 5000 caracteres incluidos los tokens, 20 personas y solo miembros con vista; los rechazados se devuelven en rejected_user_ids", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollaborationCommentWriteProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Backoffice - Collaboration - Comments" ], "summary": "Delete a collection comment", "description": "Requires collections.view and company membership. The parent Collection and evidence ids must belong to the route company and parent. Comments are plain text. Authors alone edit comments; authors/uploaders or company administrators delete their evidence. A screenshot reports payment evidence and never sets or confirms the informational crediting date.", "operationId": "95d5af0febdc400a71953447e7bf6828", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "commentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Delete a collection comment" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "oneOf": [ { "required": [ "message" ], "properties": { "message": { "type": "string" } }, "type": "object" } ] } } } }, "403": { "description": "Missing collections.view or company membership; actor cannot edit/delete another user evidence or attach to another user comment", "content": { "application/json": { "schema": { "oneOf": [ { "required": [ "message" ], "properties": { "message": { "type": "string" } }, "type": "object" }, { "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "error_code": { "type": "string", "nullable": true }, "errors": { "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" } ] } } } }, "404": { "description": "Collection, scoped comment or attachment not found; foreign parents and substituted evidence ids are hidden", "content": { "application/json": { "schema": { "oneOf": [ { "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "error_code": { "type": "string", "nullable": true }, "errors": { "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/sales-invoices/{documentId}/comments/{commentId}": { "put": { "tags": [ "Backoffice - Collaboration - Comments" ], "summary": "Edit a comment on a sales invoice", "description": "Author-only edit. Sets edited_at to now.", "operationId": "7e13fec75fb4d2fe01ef9ce153444085", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "commentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "body" ], "properties": { "body": { "description": "Texto plano, incluidos los tokens @[Nombre](user:id); máximo 20 personas mencionadas", "type": "string", "maxLength": 5000 } }, "type": "object" } } } }, "responses": { "200": { "description": "Comment updated" }, "403": { "description": "Actor is not the author", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Forbidden" }, "status": { "type": "integer", "example": 403 }, "error_code": { "type": "string", "example": "comment_not_authored_by_actor" } }, "type": "object" } } } }, "404": { "description": "Document or comment not found, or a path id that is not a UUID, which the router answers before the controller with a `message` body.", "content": { "application/json": { "schema": { "oneOf": [ { "required": [ "title", "status", "error_code" ], "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "error_code": { "type": "string", "example": "comment_not_found" } }, "type": "object" }, { "required": [ "message" ], "properties": { "message": { "type": "string" } }, "type": "object" } ] } } } }, "422": { "description": "Validación del texto o las menciones: máximo 5000 caracteres incluidos los tokens, 20 personas y solo miembros con vista; los rechazados se devuelven en rejected_user_ids", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollaborationCommentWriteProblem" } } } }, "401": { "description": "Unauthenticated" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Backoffice - Collaboration - Comments" ], "summary": "Delete a comment on a sales invoice", "description": "Hard-deletes the comment. Author or company admin (AuthorizationPolicy::isAdmin) may delete.", "operationId": "3f02748ecbdb23d4628e7c6f45f27c4f", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "commentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Comment deleted" }, "403": { "description": "Actor is not the author and is not an admin", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Forbidden" }, "status": { "type": "integer", "example": 403 }, "error_code": { "type": "string", "example": "comment_not_authored_by_actor" } }, "type": "object" } } } }, "404": { "description": "Document or comment not found, or a path id that is not a UUID, which the router answers before the controller with a `message` body.", "content": { "application/json": { "schema": { "oneOf": [ { "required": [ "title", "status", "error_code" ], "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "error_code": { "type": "string", "example": "comment_not_found" } }, "type": "object" }, { "required": [ "message" ], "properties": { "message": { "type": "string" } }, "type": "object" } ] } } } }, "401": { "description": "Unauthenticated" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/sales-orders/{documentId}/comments/{commentId}": { "put": { "tags": [ "Backoffice - Collaboration - Comments" ], "summary": "Edit a comment on a sales order", "description": "Author-only edit. Sets edited_at to now.", "operationId": "8d465484e40ebaf8ea266e06a1085551", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "commentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "body" ], "properties": { "body": { "description": "Texto plano, incluidos los tokens @[Nombre](user:id); máximo 20 personas mencionadas", "type": "string", "maxLength": 5000 } }, "type": "object" } } } }, "responses": { "200": { "description": "Comment updated" }, "403": { "description": "Actor is not the author", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Forbidden" }, "status": { "type": "integer", "example": 403 }, "error_code": { "type": "string", "example": "comment_not_authored_by_actor" } }, "type": "object" } } } }, "404": { "description": "Document or comment not found", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "error_code": { "type": "string", "example": "comment_not_found" } }, "type": "object" } } } }, "422": { "description": "Validación del texto o las menciones: máximo 5000 caracteres incluidos los tokens, 20 personas y solo miembros con vista; los rechazados se devuelven en rejected_user_ids", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollaborationCommentWriteProblem" } } } }, "401": { "description": "Unauthenticated" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Backoffice - Collaboration - Comments" ], "summary": "Delete a comment on a sales order", "description": "Hard-deletes the comment. Author or company admin (AuthorizationPolicy::isAdmin) may delete.", "operationId": "d5679087f0faf3198d3c29c1f22dd59e", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "commentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Comment deleted" }, "403": { "description": "Actor is not the author and is not an admin", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Forbidden" }, "status": { "type": "integer", "example": 403 }, "error_code": { "type": "string", "example": "comment_not_authored_by_actor" } }, "type": "object" } } } }, "404": { "description": "Document or comment not found", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "error_code": { "type": "string", "example": "comment_not_found" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/contracts/{documentId}/comments/{commentId}": { "put": { "tags": [ "Backoffice - Collaboration - Comments" ], "summary": "CommentPut on a Purchase Contract", "description": "Author-only edit. Sets edited_at to now.", "operationId": "a2f30b988a62ea11976078e10f97e14e", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "commentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "body" ], "properties": { "body": { "description": "Texto plano, incluidos los tokens @[Nombre](user:id); máximo 20 personas mencionadas", "type": "string", "maxLength": 5000 } }, "type": "object" } } } }, "responses": { "200": { "description": "Comment updated" }, "403": { "description": "Forbidden: permission, membership or evidence ownership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } ] } } } }, "404": { "description": "Document or scoped evidence not found", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } ] } } } }, "422": { "description": "Validación del texto o las menciones: máximo 5000 caracteres incluidos los tokens, 20 personas y solo miembros con vista; los rechazados se devuelven en rejected_user_ids", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollaborationCommentWriteProblem" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Backoffice - Collaboration - Comments" ], "summary": "CommentDelete on a Purchase Contract", "description": "Hard-deletes the comment. Author or company admin (AuthorizationPolicy::isAdmin) may delete.", "operationId": "c9178e2a8b9998d843a87bd5557cbd77", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "commentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Comment deleted" }, "403": { "description": "Forbidden: permission, membership or evidence ownership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } ] } } } }, "404": { "description": "Document or scoped evidence not found", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/contract-activations/{documentId}/comments/{commentId}": { "put": { "tags": [ "Backoffice - Collaboration - Comments" ], "summary": "CommentPut on a Purchase Contract Activation", "description": "Author-only edit. Sets edited_at to now.", "operationId": "71f62241985b5bd939d743bd13d97e00", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "commentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "body" ], "properties": { "body": { "description": "Texto plano, incluidos los tokens @[Nombre](user:id); máximo 20 personas mencionadas", "type": "string", "maxLength": 5000 } }, "type": "object" } } } }, "responses": { "200": { "description": "Comment updated" }, "403": { "description": "Forbidden: permission, membership or evidence ownership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } ] } } } }, "404": { "description": "Document or scoped evidence not found", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } ] } } } }, "422": { "description": "Validación del texto o las menciones: máximo 5000 caracteres incluidos los tokens, 20 personas y solo miembros con vista; los rechazados se devuelven en rejected_user_ids", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollaborationCommentWriteProblem" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Backoffice - Collaboration - Comments" ], "summary": "CommentDelete on a Purchase Contract Activation", "description": "Hard-deletes the comment. Author or company admin (AuthorizationPolicy::isAdmin) may delete.", "operationId": "a8735d754119d8dee546ffb78f048cc6", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "commentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Comment deleted" }, "403": { "description": "Forbidden: permission, membership or evidence ownership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } ] } } } }, "404": { "description": "Document or scoped evidence not found", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/contract-addenda/{documentId}/comments/{commentId}": { "put": { "tags": [ "Backoffice - Collaboration - Comments" ], "summary": "CommentPut on a Purchase Contract Addendum", "description": "Author-only edit. Sets edited_at to now.", "operationId": "4ab6917bcc8cc34ceebb137c46bcfcf7", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "commentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "body" ], "properties": { "body": { "description": "Texto plano, incluidos los tokens @[Nombre](user:id); máximo 20 personas mencionadas", "type": "string", "maxLength": 5000 } }, "type": "object" } } } }, "responses": { "200": { "description": "Comment updated" }, "403": { "description": "Forbidden: permission, membership or evidence ownership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } ] } } } }, "404": { "description": "Document or scoped evidence not found", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } ] } } } }, "422": { "description": "Validación del texto o las menciones: máximo 5000 caracteres incluidos los tokens, 20 personas y solo miembros con vista; los rechazados se devuelven en rejected_user_ids", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollaborationCommentWriteProblem" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Backoffice - Collaboration - Comments" ], "summary": "CommentDelete on a Purchase Contract Addendum", "description": "Hard-deletes the comment. Author or company admin (AuthorizationPolicy::isAdmin) may delete.", "operationId": "1ed620f27b6f6ea734224164f0d259cb", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "commentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Comment deleted" }, "403": { "description": "Forbidden: permission, membership or evidence ownership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } ] } } } }, "404": { "description": "Document or scoped evidence not found", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/contract-deactivations/{documentId}/comments/{commentId}": { "put": { "tags": [ "Backoffice - Collaboration - Comments" ], "summary": "CommentPut on a Purchase Contract Deactivation", "description": "Author-only edit. Sets edited_at to now.", "operationId": "1da9836a93e89ffa092a70f6b340a69e", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "commentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "body" ], "properties": { "body": { "description": "Texto plano, incluidos los tokens @[Nombre](user:id); máximo 20 personas mencionadas", "type": "string", "maxLength": 5000 } }, "type": "object" } } } }, "responses": { "200": { "description": "Comment updated" }, "403": { "description": "Forbidden: permission, membership or evidence ownership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } ] } } } }, "404": { "description": "Document or scoped evidence not found", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } ] } } } }, "422": { "description": "Validación del texto o las menciones: máximo 5000 caracteres incluidos los tokens, 20 personas y solo miembros con vista; los rechazados se devuelven en rejected_user_ids", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollaborationCommentWriteProblem" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Backoffice - Collaboration - Comments" ], "summary": "CommentDelete on a Purchase Contract Deactivation", "description": "Hard-deletes the comment. Author or company admin (AuthorizationPolicy::isAdmin) may delete.", "operationId": "d6d199b867289e69e9fa5d099d308163", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "commentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Comment deleted" }, "403": { "description": "Forbidden: permission, membership or evidence ownership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } ] } } } }, "404": { "description": "Document or scoped evidence not found", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/contracts/{contractId}/comments/{commentId}": { "put": { "tags": [ "Backoffice - Collaboration - Comments" ], "summary": "CommentPut on a Sales Contract", "description": "Author-only edit. Sets edited_at to now.", "operationId": "afcb88b195ee7734689abd59c347630b", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "contractId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "commentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "body" ], "properties": { "body": { "description": "Texto plano, incluidos los tokens @[Nombre](user:id); máximo 20 personas mencionadas", "type": "string", "maxLength": 5000 } }, "type": "object" } } } }, "responses": { "200": { "description": "Comment updated" }, "403": { "description": "Forbidden: permission, membership or evidence ownership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractProblemResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareForbiddenResponse" } ] } } } }, "404": { "description": "Document or scoped evidence not found", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractProblemResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } ] } } } }, "422": { "description": "Validación del texto o las menciones: máximo 5000 caracteres incluidos los tokens, 20 personas y solo miembros con vista; los rechazados se devuelven en rejected_user_ids", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollaborationCommentWriteProblem" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Backoffice - Collaboration - Comments" ], "summary": "CommentDelete on a Sales Contract", "description": "Hard-deletes the comment. Author or company admin (AuthorizationPolicy::isAdmin) may delete.", "operationId": "aa7160c07ee725edabb52b29606f07ee", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "contractId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "commentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Comment deleted" }, "403": { "description": "Forbidden: permission, membership or evidence ownership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractProblemResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareForbiddenResponse" } ] } } } }, "404": { "description": "Document or scoped evidence not found", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractProblemResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/contract-activations/{activationId}/comments/{commentId}": { "put": { "tags": [ "Backoffice - Collaboration - Comments" ], "summary": "CommentPut on a Sales Contract Activation", "description": "Author-only edit. Sets edited_at to now.", "operationId": "60e135f9006984a0842ea9f8bd454713", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "activationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "commentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "body" ], "properties": { "body": { "description": "Texto plano, incluidos los tokens @[Nombre](user:id); máximo 20 personas mencionadas", "type": "string", "maxLength": 5000 } }, "type": "object" } } } }, "responses": { "200": { "description": "Comment updated" }, "403": { "description": "Forbidden: permission, membership or evidence ownership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractProblemResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareForbiddenResponse" } ] } } } }, "404": { "description": "Document or scoped evidence not found", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractProblemResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } ] } } } }, "422": { "description": "Validación del texto o las menciones: máximo 5000 caracteres incluidos los tokens, 20 personas y solo miembros con vista; los rechazados se devuelven en rejected_user_ids", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollaborationCommentWriteProblem" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Backoffice - Collaboration - Comments" ], "summary": "CommentDelete on a Sales Contract Activation", "description": "Hard-deletes the comment. Author or company admin (AuthorizationPolicy::isAdmin) may delete.", "operationId": "74172370a7362e30637c5d5ca3f877d0", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "activationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "commentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Comment deleted" }, "403": { "description": "Forbidden: permission, membership or evidence ownership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractProblemResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareForbiddenResponse" } ] } } } }, "404": { "description": "Document or scoped evidence not found", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractProblemResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/contract-deactivations/{deactivationId}/comments/{commentId}": { "put": { "tags": [ "Backoffice - Collaboration - Comments" ], "summary": "CommentPut on a Sales Contract Deactivation", "description": "Author-only edit. Sets edited_at to now.", "operationId": "50254b8b1b625c2841005e73c2520911", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "deactivationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "commentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "body" ], "properties": { "body": { "description": "Texto plano, incluidos los tokens @[Nombre](user:id); máximo 20 personas mencionadas", "type": "string", "maxLength": 5000 } }, "type": "object" } } } }, "responses": { "200": { "description": "Comment updated" }, "403": { "description": "Forbidden: permission, membership or evidence ownership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractProblemResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareForbiddenResponse" } ] } } } }, "404": { "description": "Document or scoped evidence not found", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractProblemResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } ] } } } }, "422": { "description": "Validación del texto o las menciones: máximo 5000 caracteres incluidos los tokens, 20 personas y solo miembros con vista; los rechazados se devuelven en rejected_user_ids", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollaborationCommentWriteProblem" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Backoffice - Collaboration - Comments" ], "summary": "CommentDelete on a Sales Contract Deactivation", "description": "Hard-deletes the comment. Author or company admin (AuthorizationPolicy::isAdmin) may delete.", "operationId": "a63795195a0c42bafab7d0712f5d5d3b", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "deactivationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "commentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Comment deleted" }, "403": { "description": "Forbidden: permission, membership or evidence ownership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractProblemResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareForbiddenResponse" } ] } } } }, "404": { "description": "Document or scoped evidence not found", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractProblemResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/items/{documentId}/comments/{commentId}": { "put": { "tags": [ "Backoffice - Inventory Items" ], "summary": "Put Item comments", "description": "Requires Item VIEW. Edit requires authorship; delete permits author or company admin. Foreign parent or mismatched child is 404.", "operationId": "5106ff3499f3a4b5725b136f8aab56f9", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "commentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "body" ], "properties": { "body": { "description": "Texto plano, incluidos los tokens @[Nombre](user:id); máximo 20 personas mencionadas", "type": "string", "maxLength": 5000, "minLength": 1 } }, "type": "object" } } } }, "responses": { "200": { "description": "Updated; empty JSON object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemEmptyResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemError" } } } }, "403": { "description": "Forbidden or tenant access refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemError" } } } }, "404": { "description": "Tenant-scoped resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemError" } } } }, "422": { "description": "Validación del texto o las menciones: máximo 5000 caracteres incluidos los tokens, 20 personas y solo miembros con vista; los rechazados se devuelven en rejected_user_ids", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollaborationCommentWriteProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Backoffice - Inventory Items" ], "summary": "Delete Item comments", "description": "Requires Item VIEW. Edit requires authorship; delete permits author or company admin. Foreign parent or mismatched child is 404.", "operationId": "3275365072ec21f91cea29abef00d901", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "commentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Success; null body" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemError" } } } }, "403": { "description": "Forbidden or tenant access refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemError" } } } }, "404": { "description": "Tenant-scoped resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemError" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/transfers/{documentId}/comments/{commentId}": { "put": { "tags": [ "Backoffice - Collaboration - Comments" ], "summary": "Edit a comment on an inventory transfer (Traslado de inventario)", "description": "Author-only edit. Sets edited_at to now.", "operationId": "8d6b6b648db6d07e35744e50c8be83a0", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "commentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "body" ], "properties": { "body": { "description": "Texto plano, incluidos los tokens @[Nombre](user:id); máximo 20 personas mencionadas", "type": "string", "maxLength": 5000 } }, "type": "object" } } } }, "responses": { "200": { "description": "Comment updated" }, "403": { "description": "Actor is not the author", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Forbidden" }, "status": { "type": "integer", "example": 403 }, "error_code": { "type": "string", "example": "comment_not_authored_by_actor" } }, "type": "object" } } } }, "404": { "description": "Document or comment not found", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "error_code": { "type": "string", "example": "comment_not_found" } }, "type": "object" } } } }, "422": { "description": "Validación del texto o las menciones: máximo 5000 caracteres incluidos los tokens, 20 personas y solo miembros con vista; los rechazados se devuelven en rejected_user_ids", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollaborationCommentWriteProblem" } } } }, "401": { "description": "Unauthenticated" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Backoffice - Collaboration - Comments" ], "summary": "Delete a comment on an inventory transfer (Traslado de inventario)", "description": "Hard-deletes the comment. Author or company admin (AuthorizationPolicy::isAdmin) may delete.", "operationId": "5edb938c6441f565b97f6927beb7d535", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "commentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Comment deleted" }, "403": { "description": "Actor is not the author and is not an admin", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Forbidden" }, "status": { "type": "integer", "example": 403 }, "error_code": { "type": "string", "example": "comment_not_authored_by_actor" } }, "type": "object" } } } }, "404": { "description": "Document or comment not found", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "error_code": { "type": "string", "example": "comment_not_found" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/treasury/transfers/{documentId}/comments/{commentId}": { "put": { "tags": [ "Backoffice - Collaboration - Comments" ], "summary": "Edit a comment on a treasury transfer (transferencia entre cuentas propias)", "description": "Author-only edit. Sets edited_at to now. Requires `backoffice.treasury.treasury-transfers.view`.", "operationId": "bd98c8ad8d0601c769513b6114c81873", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "commentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "body" ], "properties": { "body": { "description": "Texto plano, incluidos los tokens @[Nombre](user:id); máximo 20 personas mencionadas", "type": "string", "maxLength": 5000 } }, "type": "object" } } } }, "responses": { "200": { "description": "Comment updated" }, "403": { "description": "Actor is not the author", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Forbidden" }, "status": { "type": "integer", "example": 403 }, "error_code": { "type": "string", "example": "comment_not_authored_by_actor" } }, "type": "object" } } } }, "404": { "description": "Document or comment not found", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "error_code": { "type": "string", "example": "comment_not_found" } }, "type": "object" } } } }, "422": { "description": "Validación del texto o las menciones: máximo 5000 caracteres incluidos los tokens, 20 personas y solo miembros con vista; los rechazados se devuelven en rejected_user_ids", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollaborationCommentWriteProblem" } } } }, "401": { "description": "Unauthenticated" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Backoffice - Collaboration - Comments" ], "summary": "Delete a comment on a treasury transfer (transferencia entre cuentas propias)", "description": "Hard-deletes the comment. Author or company admin (AuthorizationPolicy::isAdmin) may delete. Requires `backoffice.treasury.treasury-transfers.view`.", "operationId": "37de623d07bb07eeb802ead158fc6bd0", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "commentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Comment deleted" }, "403": { "description": "Actor is not the author and is not an admin", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Forbidden" }, "status": { "type": "integer", "example": 403 }, "error_code": { "type": "string", "example": "comment_not_authored_by_actor" } }, "type": "object" } } } }, "404": { "description": "Document or comment not found", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "error_code": { "type": "string", "example": "comment_not_found" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/dispatches/{documentId}/comments/{commentId}": { "put": { "tags": [ "Backoffice - Collaboration - Comments" ], "summary": "Edit a comment on an inventory dispatch (Despacho de inventario)", "description": "Author-only edit. Sets edited_at to now.", "operationId": "0e1646ed9c5598789e70104a29cf3e67", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "commentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "body" ], "properties": { "body": { "description": "Texto plano, incluidos los tokens @[Nombre](user:id); máximo 20 personas mencionadas", "type": "string", "maxLength": 5000 } }, "type": "object" } } } }, "responses": { "200": { "description": "Empty JSON object acknowledgement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryDispatchAcknowledgement" } } } }, "403": { "description": "HTTP 403; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryDispatchForbidden" } } } }, "404": { "description": "HTTP 404; document, child and company scope are enforced", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/InventoryDispatchProblem" }, { "$ref": "#/components/schemas/InventoryDispatchUnauthenticated" } ] } } } }, "422": { "description": "Validación del texto o las menciones: máximo 5000 caracteres incluidos los tokens, 20 personas y solo miembros con vista; los rechazados se devuelven en rejected_user_ids", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollaborationCommentWriteProblem" } } } }, "401": { "description": "HTTP 401; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryDispatchUnauthenticated" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Backoffice - Collaboration - Comments" ], "summary": "Delete a comment on an inventory dispatch (Despacho de inventario)", "description": "Hard-deletes the comment. Author or company admin (AuthorizationPolicy::isAdmin) may delete.", "operationId": "06c781b06275e54d4787148d90319457", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "commentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Comment deleted" }, "403": { "description": "HTTP 403; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryDispatchForbidden" } } } }, "404": { "description": "HTTP 404; document, child and company scope are enforced", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/InventoryDispatchProblem" }, { "$ref": "#/components/schemas/InventoryDispatchUnauthenticated" } ] } } } }, "401": { "description": "HTTP 401; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryDispatchUnauthenticated" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/entries/{documentId}/comments/{commentId}": { "put": { "tags": [ "Backoffice - Collaboration - Comments" ], "summary": "Edit a comment on an inventory entry (Entrada de inventario)", "description": "Author-only edit. Sets edited_at to now.", "operationId": "3e42c415b86a958fc1beebdfdebda501", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "commentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "body" ], "properties": { "body": { "description": "Texto plano, incluidos los tokens @[Nombre](user:id); máximo 20 personas mencionadas", "type": "string", "maxLength": 5000 } }, "type": "object" } } } }, "responses": { "200": { "description": "Empty JSON object acknowledgement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryEntryAcknowledgement" } } } }, "403": { "description": "HTTP 403; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryEntryForbidden" } } } }, "404": { "description": "HTTP 404; document, child and company scope are enforced", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/InventoryEntryProblem" }, { "$ref": "#/components/schemas/InventoryEntryUnauthenticated" } ] } } } }, "422": { "description": "Validación del texto o las menciones: máximo 5000 caracteres incluidos los tokens, 20 personas y solo miembros con vista; los rechazados se devuelven en rejected_user_ids", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollaborationCommentWriteProblem" } } } }, "401": { "description": "HTTP 401; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryEntryUnauthenticated" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Backoffice - Collaboration - Comments" ], "summary": "Delete a comment on an inventory entry (Entrada de inventario)", "description": "Hard-deletes the comment. Author or company admin (AuthorizationPolicy::isAdmin) may delete.", "operationId": "a5e6a03ad8755de02a2c3d743ee3f030", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "commentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Comment deleted" }, "403": { "description": "HTTP 403; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryEntryForbidden" } } } }, "404": { "description": "HTTP 404; document, child and company scope are enforced", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/InventoryEntryProblem" }, { "$ref": "#/components/schemas/InventoryEntryUnauthenticated" } ] } } } }, "401": { "description": "HTTP 401; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryEntryUnauthenticated" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/transformations/{documentId}/comments/{commentId}": { "put": { "tags": [ "Backoffice - Collaboration - Comments" ], "summary": "Edit a comment on a transformation (Transformación de ítems)", "description": "Author-only edit. Sets edited_at to now.", "operationId": "2dc8470b0dc93565bc5ad01812cc8776", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "commentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "body" ], "properties": { "body": { "description": "Texto plano, incluidos los tokens @[Nombre](user:id); máximo 20 personas mencionadas", "type": "string", "maxLength": 5000 } }, "type": "object" } } } }, "responses": { "200": { "description": "Empty JSON object acknowledgement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransformationAcknowledgement" } } } }, "403": { "description": "HTTP 403; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransformationForbidden" } } } }, "404": { "description": "HTTP 404; document, child and company scope are enforced", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/TransformationProblem" }, { "$ref": "#/components/schemas/TransformationUnauthenticated" } ] } } } }, "422": { "description": "Validación del texto o las menciones: máximo 5000 caracteres incluidos los tokens, 20 personas y solo miembros con vista; los rechazados se devuelven en rejected_user_ids", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollaborationCommentWriteProblem" } } } }, "401": { "description": "HTTP 401; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransformationUnauthenticated" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Backoffice - Collaboration - Comments" ], "summary": "Delete a comment on a transformation (Transformación de ítems)", "description": "Hard-deletes the comment. Author or company admin (AuthorizationPolicy::isAdmin) may delete.", "operationId": "34b451a1e657bf6e3ff1b62b2de1947e", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "commentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Comment deleted" }, "403": { "description": "HTTP 403; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransformationForbidden" } } } }, "404": { "description": "HTTP 404; document, child and company scope are enforced", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/TransformationProblem" }, { "$ref": "#/components/schemas/TransformationUnauthenticated" } ] } } } }, "401": { "description": "HTTP 401; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransformationUnauthenticated" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/adjustments/{documentId}/comments/{commentId}": { "put": { "tags": [ "Backoffice - Collaboration - Comments" ], "summary": "Edit a comment on an inventory adjustment (Ajuste de inventario)", "description": "Author-only edit. Sets edited_at to now.", "operationId": "6ec79137e1cf5f28164158cb12b4025c", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "commentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "body" ], "properties": { "body": { "description": "Texto plano, incluidos los tokens @[Nombre](user:id); máximo 20 personas mencionadas", "type": "string", "maxLength": 5000 } }, "type": "object" } } } }, "responses": { "200": { "description": "Empty JSON object acknowledgement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdjustmentAcknowledgement" } } } }, "403": { "description": "HTTP 403; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdjustmentForbidden" } } } }, "404": { "description": "HTTP 404; document, child and company scope are enforced", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/AdjustmentProblem" }, { "$ref": "#/components/schemas/AdjustmentUnauthenticated" } ] } } } }, "422": { "description": "Validación del texto o las menciones: máximo 5000 caracteres incluidos los tokens, 20 personas y solo miembros con vista; los rechazados se devuelven en rejected_user_ids", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollaborationCommentWriteProblem" } } } }, "401": { "description": "HTTP 401; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdjustmentUnauthenticated" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Backoffice - Collaboration - Comments" ], "summary": "Delete a comment on an inventory adjustment (Ajuste de inventario)", "description": "Hard-deletes the comment. Author or company admin (AuthorizationPolicy::isAdmin) may delete.", "operationId": "4ddbd163b60a87caa5c068fa5ae981fc", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "commentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Comment deleted" }, "403": { "description": "HTTP 403; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdjustmentForbidden" } } } }, "404": { "description": "HTTP 404; document, child and company scope are enforced", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/AdjustmentProblem" }, { "$ref": "#/components/schemas/AdjustmentUnauthenticated" } ] } } } }, "401": { "description": "HTTP 401; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdjustmentUnauthenticated" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/credit-notes/{documentId}/comments/{commentId}": { "put": { "tags": [ "Backoffice - Collaboration - Comments" ], "summary": "Edit a comment on a supplier nota de crédito de proveedor", "description": "Requires `backoffice.purchases.credit-notes.view`. Author-only edit. Sets edited_at to now.", "operationId": "77ba8363575e8d9a9b6c887fdde9158c", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "commentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "body" ], "properties": { "body": { "description": "Texto plano, incluidos los tokens @[Nombre](user:id); máximo 20 personas mencionadas", "type": "string", "maxLength": 5000 } }, "type": "object" } } } }, "responses": { "200": { "description": "Comment updated" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden: missing backoffice.purchases.credit-notes.view or not the author" }, "404": { "description": "Document or comment not found" }, "422": { "description": "Validación del texto o las menciones: máximo 5000 caracteres incluidos los tokens, 20 personas y solo miembros con vista; los rechazados se devuelven en rejected_user_ids", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollaborationCommentWriteProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Backoffice - Collaboration - Comments" ], "summary": "Delete a comment on a supplier nota de crédito de proveedor", "description": "Requires `backoffice.purchases.credit-notes.view`. Hard-deletes the comment. Author or company admin may delete.", "operationId": "e438bbf4957022f80c868975a405ebaf", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "commentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Comment deleted" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden: missing backoffice.purchases.credit-notes.view or not allowed to delete" }, "404": { "description": "Document or comment not found" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/debit-notes/{documentId}/comments/{commentId}": { "put": { "tags": [ "Backoffice - Collaboration - Comments" ], "summary": "Edit a comment on a supplier nota de débito de proveedor", "description": "Requires `backoffice.purchases.debit-notes.view`. Author-only edit. Sets edited_at to now.", "operationId": "9e56a8076d2ff367e886301966990f60", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "commentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "body" ], "properties": { "body": { "description": "Texto plano, incluidos los tokens @[Nombre](user:id); máximo 20 personas mencionadas", "type": "string", "maxLength": 5000 } }, "type": "object" } } } }, "responses": { "200": { "description": "Comment updated" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden: missing backoffice.purchases.debit-notes.view or not the author" }, "404": { "description": "Document or comment not found" }, "422": { "description": "Validación del texto o las menciones: máximo 5000 caracteres incluidos los tokens, 20 personas y solo miembros con vista; los rechazados se devuelven en rejected_user_ids", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollaborationCommentWriteProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Backoffice - Collaboration - Comments" ], "summary": "Delete a comment on a supplier nota de débito de proveedor", "description": "Requires `backoffice.purchases.debit-notes.view`. Hard-deletes the comment. Author or company admin may delete.", "operationId": "c2b02ad8245c76d17312d373d01c9044", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "commentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Comment deleted" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden: missing backoffice.purchases.debit-notes.view or not allowed to delete" }, "404": { "description": "Document or comment not found" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/orders/{documentId}/comments": { "get": { "tags": [ "Backoffice - Collaboration - Comments" ], "summary": "List comments on a purchase order (Pedido)", "description": "Returns every comment on the Pedido ordered by created_at ascending. `can_edit` / `can_delete` are computed for the authenticated actor.", "operationId": "1e1d6f7a01d34b8525bdcdf6317ca528", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Comment list", "content": { "application/json": { "schema": { "properties": { "items": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "body": { "type": "string" }, "author_user_id": { "type": "integer" }, "mentions": { "type": "array", "items": { "required": [ "user_id", "name" ], "properties": { "user_id": { "type": "integer" }, "name": { "type": "string" } }, "type": "object" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "edited_at": { "type": "string", "format": "date-time", "nullable": true }, "parent_id": { "type": "string", "format": "uuid", "nullable": true }, "is_deleted": { "type": "boolean" }, "can_edit": { "type": "boolean" }, "can_delete": { "type": "boolean" } }, "type": "object" } } }, "type": "object" } } } }, "404": { "description": "Document not found", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "error_code": { "type": "string", "example": "collaboration_document_not_found" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Collaboration - Comments" ], "summary": "Post a comment on a purchase order (Pedido)", "description": "Appends a plain-text comment. The client supplies a UUIDv7 id. Duplicate ids answer 409.", "operationId": "ad8bb2ea264fd6a2af40f37cfd619b0b", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "id", "body" ], "properties": { "parent_id": { "description": "Same-document comment; replies resolve to its root.", "type": "string", "format": "uuid", "nullable": true }, "id": { "type": "string", "format": "uuid", "example": "0190b7a0-1111-7222-8333-444455556666" }, "body": { "description": "Texto plano, incluidos los tokens @[Nombre](user:id); máximo 20 personas mencionadas", "type": "string", "example": "Need confirmation on the delivery window.", "maxLength": 5000 } }, "type": "object" } } } }, "responses": { "201": { "description": "Comment posted" }, "404": { "description": "Document not found", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "error_code": { "type": "string", "example": "collaboration_document_not_found" } }, "type": "object" } } } }, "409": { "description": "Duplicate comment ID", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "error_code": { "type": "string", "example": "comment_already_exists" } }, "type": "object" } } } }, "422": { "description": "Validación del texto o las menciones: máximo 5000 caracteres incluidos los tokens, 20 personas y solo miembros con vista; los rechazados se devuelven en rejected_user_ids", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollaborationCommentWriteProblem" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/purchases-orders/{documentId}/comments": { "get": { "tags": [ "Backoffice - Collaboration - Comments" ], "summary": "List comments on a purchase order (Orden de compra)", "description": "Returns every comment on the Orden de compra ordered by created_at ascending. `can_edit` / `can_delete` are computed for the authenticated actor.", "operationId": "ddb7a1d455c24b2ede649612530a18b4", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Comment list", "content": { "application/json": { "schema": { "properties": { "items": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "body": { "type": "string" }, "author_user_id": { "type": "integer" }, "mentions": { "type": "array", "items": { "required": [ "user_id", "name" ], "properties": { "user_id": { "type": "integer" }, "name": { "type": "string" } }, "type": "object" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "edited_at": { "type": "string", "format": "date-time", "nullable": true }, "parent_id": { "type": "string", "format": "uuid", "nullable": true }, "is_deleted": { "type": "boolean" }, "can_edit": { "type": "boolean" }, "can_delete": { "type": "boolean" } }, "type": "object" } } }, "type": "object" } } } }, "404": { "description": "Document not found", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "error_code": { "type": "string", "example": "collaboration_document_not_found" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Collaboration - Comments" ], "summary": "Post a comment on a purchase order (Orden de compra)", "description": "Appends a plain-text comment. The client supplies a UUIDv7 id. Duplicate ids answer 409.", "operationId": "4b8f114b7282fd69b02333a715da3582", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "id", "body" ], "properties": { "parent_id": { "description": "Same-document comment; replies resolve to its root.", "type": "string", "format": "uuid", "nullable": true }, "id": { "type": "string", "format": "uuid", "example": "0190b7a0-1111-7222-8333-444455556666" }, "body": { "description": "Texto plano, incluidos los tokens @[Nombre](user:id); máximo 20 personas mencionadas", "type": "string", "example": "Need confirmation on the delivery window.", "maxLength": 5000 } }, "type": "object" } } } }, "responses": { "201": { "description": "Comment posted" }, "404": { "description": "Document not found", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "error_code": { "type": "string", "example": "collaboration_document_not_found" } }, "type": "object" } } } }, "409": { "description": "Duplicate comment ID", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "error_code": { "type": "string", "example": "comment_already_exists" } }, "type": "object" } } } }, "422": { "description": "Validación del texto o las menciones: máximo 5000 caracteres incluidos los tokens, 20 personas y solo miembros con vista; los rechazados se devuelven en rejected_user_ids", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollaborationCommentWriteProblem" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/providers/{documentId}/comments": { "get": { "tags": [ "Backoffice - Collaboration - Comments" ], "summary": "List comments on a provider", "description": "Requiere `backoffice.purchases.providers.view`. Devuelve todos los comentarios del proveedor ordenados por created_at ascendente. `can_edit` / `can_delete` se calculan para el usuario autenticado.", "operationId": "97f37cf5dca97f4d24e13fff55244826", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Comment list", "content": { "application/json": { "schema": { "properties": { "items": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "body": { "type": "string" }, "author_user_id": { "type": "integer" }, "mentions": { "type": "array", "items": { "required": [ "user_id", "name" ], "properties": { "user_id": { "type": "integer" }, "name": { "type": "string" } }, "type": "object" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "edited_at": { "type": "string", "format": "date-time", "nullable": true }, "parent_id": { "type": "string", "format": "uuid", "nullable": true }, "is_deleted": { "type": "boolean" }, "can_edit": { "type": "boolean" }, "can_delete": { "type": "boolean" } }, "type": "object" } } }, "type": "object" } } } }, "404": { "description": "Document not found", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "error_code": { "type": "string", "example": "collaboration_document_not_found" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Collaboration - Comments" ], "summary": "Post a comment on a provider", "description": "Requires `backoffice.purchases.providers.view`. Appends a plain-text comment. The client supplies a UUIDv7 id. Duplicate ids answer 409.", "operationId": "a9d5039fc5dc42596a0aaaa1706a0247", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "id", "body" ], "properties": { "parent_id": { "description": "Same-document comment; replies resolve to its root.", "type": "string", "format": "uuid", "nullable": true }, "id": { "type": "string", "format": "uuid", "example": "0190b7a0-1111-7222-8333-444455556666" }, "body": { "description": "Texto plano, incluidos los tokens @[Nombre](user:id); máximo 20 personas mencionadas", "type": "string", "example": "Need confirmation on the delivery window.", "maxLength": 5000 } }, "type": "object" } } } }, "responses": { "201": { "description": "Comment posted" }, "404": { "description": "Document not found", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "error_code": { "type": "string", "example": "collaboration_document_not_found" } }, "type": "object" } } } }, "409": { "description": "Duplicate comment ID", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "error_code": { "type": "string", "example": "comment_already_exists" } }, "type": "object" } } } }, "422": { "description": "Validación del texto o las menciones: máximo 5000 caracteres incluidos los tokens, 20 personas y solo miembros con vista; los rechazados se devuelven en rejected_user_ids", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollaborationCommentWriteProblem" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/collections/{documentId}/comments": { "get": { "tags": [ "Backoffice - Collaboration - Comments" ], "summary": "List collection comments", "description": "Requires collections.view and company membership. The parent Collection and evidence ids must belong to the route company and parent. Comments are plain text. Authors alone edit comments; authors/uploaders or company administrators delete their evidence. A screenshot reports payment evidence and never sets or confirms the informational crediting date.", "operationId": "6e1526afd79944a235c71487dfc5becb", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "List collection comments", "content": { "application/json": { "schema": { "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "body": { "type": "string" }, "author_user_id": { "type": "integer" }, "mentions": { "type": "array", "items": { "required": [ "user_id", "name" ], "properties": { "user_id": { "type": "integer" }, "name": { "type": "string" } }, "type": "object" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "edited_at": { "type": "string", "format": "date-time", "nullable": true }, "parent_id": { "type": "string", "format": "uuid", "nullable": true }, "is_deleted": { "type": "boolean" }, "can_edit": { "type": "boolean" }, "can_delete": { "type": "boolean" } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "oneOf": [ { "required": [ "message" ], "properties": { "message": { "type": "string" } }, "type": "object" } ] } } } }, "403": { "description": "Missing collections.view or company membership; actor cannot edit/delete another user evidence or attach to another user comment", "content": { "application/json": { "schema": { "oneOf": [ { "required": [ "message" ], "properties": { "message": { "type": "string" } }, "type": "object" }, { "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "error_code": { "type": "string", "nullable": true }, "errors": { "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" } ] } } } }, "404": { "description": "Collection, scoped comment or attachment not found; foreign parents and substituted evidence ids are hidden", "content": { "application/json": { "schema": { "oneOf": [ { "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "error_code": { "type": "string", "nullable": true }, "errors": { "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Collaboration - Comments" ], "summary": "Post a collection comment", "description": "Requires collections.view and company membership. The parent Collection and evidence ids must belong to the route company and parent. Comments are plain text. Authors alone edit comments; authors/uploaders or company administrators delete their evidence. A screenshot reports payment evidence and never sets or confirms the informational crediting date.", "operationId": "b84485153386d092c36680832e1f48bb", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "id", "body" ], "properties": { "parent_id": { "description": "Same-document comment; replies resolve to its root.", "type": "string", "format": "uuid", "nullable": true }, "id": { "description": "Client-supplied UUIDv7", "type": "string", "format": "uuid" }, "body": { "description": "Texto plano, incluidos los tokens @[Nombre](user:id); máximo 20 personas mencionadas", "type": "string", "maxLength": 5000 } }, "type": "object" } } } }, "responses": { "201": { "description": "Post a collection comment" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "oneOf": [ { "required": [ "message" ], "properties": { "message": { "type": "string" } }, "type": "object" } ] } } } }, "403": { "description": "Missing collections.view or company membership; actor cannot edit/delete another user evidence or attach to another user comment", "content": { "application/json": { "schema": { "oneOf": [ { "required": [ "message" ], "properties": { "message": { "type": "string" } }, "type": "object" }, { "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "error_code": { "type": "string", "nullable": true }, "errors": { "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" } ] } } } }, "404": { "description": "Collection, scoped comment or attachment not found; foreign parents and substituted evidence ids are hidden", "content": { "application/json": { "schema": { "oneOf": [ { "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "error_code": { "type": "string", "nullable": true }, "errors": { "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" } ] } } } }, "422": { "description": "Validación del texto o las menciones: máximo 5000 caracteres incluidos los tokens, 20 personas y solo miembros con vista; los rechazados se devuelven en rejected_user_ids", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollaborationCommentWriteProblem" } } } }, "409": { "description": "Client-supplied evidence id already exists", "content": { "application/json": { "schema": { "oneOf": [ { "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "error_code": { "type": "string", "nullable": true }, "errors": { "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/sales-invoices/{documentId}/comments": { "get": { "tags": [ "Backoffice - Collaboration - Comments" ], "summary": "List comments on a sales invoice", "description": "Returns every comment on the factura de venta ordered by created_at ascending. `can_edit` / `can_delete` are computed for the authenticated actor.", "operationId": "457fa5a76ecee00e9911a633ec8a3e93", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Comment list", "content": { "application/json": { "schema": { "properties": { "items": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "body": { "type": "string" }, "author_user_id": { "type": "integer" }, "mentions": { "type": "array", "items": { "required": [ "user_id", "name" ], "properties": { "user_id": { "type": "integer" }, "name": { "type": "string" } }, "type": "object" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "edited_at": { "type": "string", "format": "date-time", "nullable": true }, "parent_id": { "type": "string", "format": "uuid", "nullable": true }, "is_deleted": { "type": "boolean" }, "can_edit": { "type": "boolean" }, "can_delete": { "type": "boolean" } }, "type": "object" } } }, "type": "object" } } } }, "404": { "description": "Document not found, or a path id that is not a UUID, which the router answers before the controller with a `message` body.", "content": { "application/json": { "schema": { "oneOf": [ { "required": [ "title", "status", "error_code" ], "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "error_code": { "type": "string", "example": "collaboration_document_not_found" } }, "type": "object" }, { "required": [ "message" ], "properties": { "message": { "type": "string" } }, "type": "object" } ] } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Collaboration - Comments" ], "summary": "Post a comment on a sales invoice", "description": "Appends a plain-text comment. The client supplies a UUIDv7 id. Duplicate ids answer 409.", "operationId": "0672989fcaec2e6352a6e027309e8bfc", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "id", "body" ], "properties": { "parent_id": { "description": "Same-document comment; replies resolve to its root.", "type": "string", "format": "uuid", "nullable": true }, "id": { "type": "string", "format": "uuid", "example": "0190b7a0-1111-7222-8333-444455556666" }, "body": { "description": "Texto plano, incluidos los tokens @[Nombre](user:id); máximo 20 personas mencionadas", "type": "string", "example": "Need confirmation on the delivery window.", "maxLength": 5000 } }, "type": "object" } } } }, "responses": { "201": { "description": "Comment posted" }, "404": { "description": "Document not found, or a path id that is not a UUID, which the router answers before the controller with a `message` body.", "content": { "application/json": { "schema": { "oneOf": [ { "required": [ "title", "status", "error_code" ], "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "error_code": { "type": "string", "example": "collaboration_document_not_found" } }, "type": "object" }, { "required": [ "message" ], "properties": { "message": { "type": "string" } }, "type": "object" } ] } } } }, "409": { "description": "Duplicate comment ID", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "error_code": { "type": "string", "example": "comment_already_exists" } }, "type": "object" } } } }, "422": { "description": "Validación del texto o las menciones: máximo 5000 caracteres incluidos los tokens, 20 personas y solo miembros con vista; los rechazados se devuelven en rejected_user_ids", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollaborationCommentWriteProblem" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/sales-orders/{documentId}/comments": { "get": { "tags": [ "Backoffice - Collaboration - Comments" ], "summary": "List comments on a sales order", "description": "Returns every comment on the orden de venta ordered by created_at ascending. `can_edit` / `can_delete` are computed for the authenticated actor.", "operationId": "c328a5cc7ace8655029602240a250872", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Comment list", "content": { "application/json": { "schema": { "properties": { "items": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "body": { "type": "string" }, "author_user_id": { "type": "integer" }, "mentions": { "type": "array", "items": { "required": [ "user_id", "name" ], "properties": { "user_id": { "type": "integer" }, "name": { "type": "string" } }, "type": "object" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "edited_at": { "type": "string", "format": "date-time", "nullable": true }, "parent_id": { "type": "string", "format": "uuid", "nullable": true }, "is_deleted": { "type": "boolean" }, "can_edit": { "type": "boolean" }, "can_delete": { "type": "boolean" } }, "type": "object" } } }, "type": "object" } } } }, "404": { "description": "Document not found", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "error_code": { "type": "string", "example": "collaboration_document_not_found" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Collaboration - Comments" ], "summary": "Post a comment on a sales order", "description": "Appends a plain-text comment. The client supplies a UUIDv7 id. Duplicate ids answer 409.", "operationId": "a7fcd783019d3d6f7173825c0d502e9a", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "id", "body" ], "properties": { "parent_id": { "description": "Same-document comment; replies resolve to its root.", "type": "string", "format": "uuid", "nullable": true }, "id": { "type": "string", "format": "uuid", "example": "0190b7a0-1111-7222-8333-444455556666" }, "body": { "description": "Texto plano, incluidos los tokens @[Nombre](user:id); máximo 20 personas mencionadas", "type": "string", "example": "Need confirmation on the delivery window.", "maxLength": 5000 } }, "type": "object" } } } }, "responses": { "201": { "description": "Comment posted" }, "404": { "description": "Document not found", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "error_code": { "type": "string", "example": "collaboration_document_not_found" } }, "type": "object" } } } }, "409": { "description": "Duplicate comment ID", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "error_code": { "type": "string", "example": "comment_already_exists" } }, "type": "object" } } } }, "422": { "description": "Validación del texto o las menciones: máximo 5000 caracteres incluidos los tokens, 20 personas y solo miembros con vista; los rechazados se devuelven en rejected_user_ids", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollaborationCommentWriteProblem" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/contracts/{documentId}/comments": { "get": { "tags": [ "Backoffice - Collaboration - Comments" ], "summary": "DocumentCommentsGet on a Purchase Contract", "description": "Returns every comment on the factura de venta ordered by created_at ascending. `can_edit` / `can_delete` are computed for the authenticated actor.", "operationId": "68f27a891d3184239f0f25f82bae7571", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Comment list", "content": { "application/json": { "schema": { "properties": { "items": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "body": { "type": "string" }, "author_user_id": { "type": "integer" }, "mentions": { "type": "array", "items": { "required": [ "user_id", "name" ], "properties": { "user_id": { "type": "integer" }, "name": { "type": "string" } }, "type": "object" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "edited_at": { "type": "string", "format": "date-time", "nullable": true }, "parent_id": { "type": "string", "format": "uuid", "nullable": true }, "is_deleted": { "type": "boolean" }, "can_edit": { "type": "boolean" }, "can_delete": { "type": "boolean" } }, "type": "object" } } }, "type": "object" } } } }, "404": { "description": "Document or scoped evidence not found", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } } } }, "403": { "description": "Forbidden: permission, membership or evidence ownership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Collaboration - Comments" ], "summary": "CommentPost on a Purchase Contract", "description": "Appends a plain-text comment. The client supplies a UUIDv7 id. Duplicate ids answer 409.", "operationId": "c235b5dddcba862fc8a91e6c34c5c373", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "id", "body" ], "properties": { "parent_id": { "description": "Same-document comment; replies resolve to its root.", "type": "string", "format": "uuid", "nullable": true }, "id": { "type": "string", "format": "uuid", "example": "0190b7a0-1111-7222-8333-444455556666" }, "body": { "description": "Texto plano, incluidos los tokens @[Nombre](user:id); máximo 20 personas mencionadas", "type": "string", "example": "Need confirmation on the delivery window.", "maxLength": 5000 } }, "type": "object" } } } }, "responses": { "201": { "description": "Comment posted" }, "404": { "description": "Document or scoped evidence not found", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } ] } } } }, "409": { "description": "Duplicate comment ID", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "error_code": { "type": "string", "example": "comment_already_exists" } }, "type": "object" } } } }, "422": { "description": "Validación del texto o las menciones: máximo 5000 caracteres incluidos los tokens, 20 personas y solo miembros con vista; los rechazados se devuelven en rejected_user_ids", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollaborationCommentWriteProblem" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } } } }, "403": { "description": "Forbidden: permission, membership or evidence ownership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/contract-activations/{documentId}/comments": { "get": { "tags": [ "Backoffice - Collaboration - Comments" ], "summary": "DocumentCommentsGet on a Purchase Contract Activation", "description": "Returns every comment on the factura de venta ordered by created_at ascending. `can_edit` / `can_delete` are computed for the authenticated actor.", "operationId": "9d78fd0408499973b80e070aaee84a8f", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Comment list", "content": { "application/json": { "schema": { "properties": { "items": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "body": { "type": "string" }, "author_user_id": { "type": "integer" }, "mentions": { "type": "array", "items": { "required": [ "user_id", "name" ], "properties": { "user_id": { "type": "integer" }, "name": { "type": "string" } }, "type": "object" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "edited_at": { "type": "string", "format": "date-time", "nullable": true }, "parent_id": { "type": "string", "format": "uuid", "nullable": true }, "is_deleted": { "type": "boolean" }, "can_edit": { "type": "boolean" }, "can_delete": { "type": "boolean" } }, "type": "object" } } }, "type": "object" } } } }, "404": { "description": "Document or scoped evidence not found", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } } } }, "403": { "description": "Forbidden: permission, membership or evidence ownership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Collaboration - Comments" ], "summary": "CommentPost on a Purchase Contract Activation", "description": "Appends a plain-text comment. The client supplies a UUIDv7 id. Duplicate ids answer 409.", "operationId": "841499dc6d63f78853e4141fc44768c7", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "id", "body" ], "properties": { "parent_id": { "description": "Same-document comment; replies resolve to its root.", "type": "string", "format": "uuid", "nullable": true }, "id": { "type": "string", "format": "uuid", "example": "0190b7a0-1111-7222-8333-444455556666" }, "body": { "description": "Texto plano, incluidos los tokens @[Nombre](user:id); máximo 20 personas mencionadas", "type": "string", "example": "Need confirmation on the delivery window.", "maxLength": 5000 } }, "type": "object" } } } }, "responses": { "201": { "description": "Comment posted" }, "404": { "description": "Document or scoped evidence not found", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } ] } } } }, "409": { "description": "Duplicate comment ID", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "error_code": { "type": "string", "example": "comment_already_exists" } }, "type": "object" } } } }, "422": { "description": "Validación del texto o las menciones: máximo 5000 caracteres incluidos los tokens, 20 personas y solo miembros con vista; los rechazados se devuelven en rejected_user_ids", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollaborationCommentWriteProblem" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } } } }, "403": { "description": "Forbidden: permission, membership or evidence ownership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/contract-addenda/{documentId}/comments": { "get": { "tags": [ "Backoffice - Collaboration - Comments" ], "summary": "DocumentCommentsGet on a Purchase Contract Addendum", "description": "Returns every comment on the factura de venta ordered by created_at ascending. `can_edit` / `can_delete` are computed for the authenticated actor.", "operationId": "a9f7061c0b81d19c252917134068d791", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Comment list", "content": { "application/json": { "schema": { "properties": { "items": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "body": { "type": "string" }, "author_user_id": { "type": "integer" }, "mentions": { "type": "array", "items": { "required": [ "user_id", "name" ], "properties": { "user_id": { "type": "integer" }, "name": { "type": "string" } }, "type": "object" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "edited_at": { "type": "string", "format": "date-time", "nullable": true }, "parent_id": { "type": "string", "format": "uuid", "nullable": true }, "is_deleted": { "type": "boolean" }, "can_edit": { "type": "boolean" }, "can_delete": { "type": "boolean" } }, "type": "object" } } }, "type": "object" } } } }, "404": { "description": "Document or scoped evidence not found", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } } } }, "403": { "description": "Forbidden: permission, membership or evidence ownership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Collaboration - Comments" ], "summary": "CommentPost on a Purchase Contract Addendum", "description": "Appends a plain-text comment. The client supplies a UUIDv7 id. Duplicate ids answer 409.", "operationId": "b2bb188df48330b991c931cf5c861f19", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "id", "body" ], "properties": { "parent_id": { "description": "Same-document comment; replies resolve to its root.", "type": "string", "format": "uuid", "nullable": true }, "id": { "type": "string", "format": "uuid", "example": "0190b7a0-1111-7222-8333-444455556666" }, "body": { "description": "Texto plano, incluidos los tokens @[Nombre](user:id); máximo 20 personas mencionadas", "type": "string", "example": "Need confirmation on the delivery window.", "maxLength": 5000 } }, "type": "object" } } } }, "responses": { "201": { "description": "Comment posted" }, "404": { "description": "Document or scoped evidence not found", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } ] } } } }, "409": { "description": "Duplicate comment ID", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "error_code": { "type": "string", "example": "comment_already_exists" } }, "type": "object" } } } }, "422": { "description": "Validación del texto o las menciones: máximo 5000 caracteres incluidos los tokens, 20 personas y solo miembros con vista; los rechazados se devuelven en rejected_user_ids", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollaborationCommentWriteProblem" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } } } }, "403": { "description": "Forbidden: permission, membership or evidence ownership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/contract-deactivations/{documentId}/comments": { "get": { "tags": [ "Backoffice - Collaboration - Comments" ], "summary": "DocumentCommentsGet on a Purchase Contract Deactivation", "description": "Returns every comment on the Desactivación de Contrato de Compra ordered by created_at ascending. `can_edit` / `can_delete` are computed for the authenticated actor.", "operationId": "3791c66f825bc1383b794eab11f606c2", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Comment list", "content": { "application/json": { "schema": { "properties": { "items": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "body": { "type": "string" }, "author_user_id": { "type": "integer" }, "mentions": { "type": "array", "items": { "required": [ "user_id", "name" ], "properties": { "user_id": { "type": "integer" }, "name": { "type": "string" } }, "type": "object" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "edited_at": { "type": "string", "format": "date-time", "nullable": true }, "parent_id": { "type": "string", "format": "uuid", "nullable": true }, "is_deleted": { "type": "boolean" }, "can_edit": { "type": "boolean" }, "can_delete": { "type": "boolean" } }, "type": "object" } } }, "type": "object" } } } }, "404": { "description": "Document or scoped evidence not found", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } } } }, "403": { "description": "Forbidden: permission, membership or evidence ownership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Collaboration - Comments" ], "summary": "CommentPost on a Purchase Contract Deactivation", "description": "Appends a plain-text comment. The client supplies a UUIDv7 id. Duplicate ids answer 409.", "operationId": "72de69b055f01748659e30cc9f82dba6", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "id", "body" ], "properties": { "parent_id": { "description": "Same-document comment; replies resolve to its root.", "type": "string", "format": "uuid", "nullable": true }, "id": { "type": "string", "format": "uuid", "example": "0190b7a0-1111-7222-8333-444455556666" }, "body": { "description": "Texto plano, incluidos los tokens @[Nombre](user:id); máximo 20 personas mencionadas", "type": "string", "example": "Need confirmation on the delivery window.", "maxLength": 5000 } }, "type": "object" } } } }, "responses": { "201": { "description": "Comment posted" }, "404": { "description": "Document or scoped evidence not found", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } ] } } } }, "409": { "description": "Duplicate comment ID", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "error_code": { "type": "string", "example": "comment_already_exists" } }, "type": "object" } } } }, "422": { "description": "Validación del texto o las menciones: máximo 5000 caracteres incluidos los tokens, 20 personas y solo miembros con vista; los rechazados se devuelven en rejected_user_ids", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollaborationCommentWriteProblem" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } } } }, "403": { "description": "Forbidden: permission, membership or evidence ownership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/contracts/{contractId}/comments": { "get": { "tags": [ "Backoffice - Collaboration - Comments" ], "summary": "DocumentCommentsGet on a Sales Contract", "description": "Returns every comment on the factura de venta ordered by created_at ascending. `can_edit` / `can_delete` are computed for the authenticated actor.", "operationId": "705ecfb0731af3678fa10ab7084c1e7c", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "contractId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Comment list", "content": { "application/json": { "schema": { "properties": { "items": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "body": { "type": "string" }, "author_user_id": { "type": "integer" }, "mentions": { "type": "array", "items": { "required": [ "user_id", "name" ], "properties": { "user_id": { "type": "integer" }, "name": { "type": "string" } }, "type": "object" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "edited_at": { "type": "string", "format": "date-time", "nullable": true }, "parent_id": { "type": "string", "format": "uuid", "nullable": true }, "is_deleted": { "type": "boolean" }, "can_edit": { "type": "boolean" }, "can_delete": { "type": "boolean" } }, "type": "object" } } }, "type": "object" } } } }, "404": { "description": "Document or scoped evidence not found", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractProblemResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } } } }, "403": { "description": "Forbidden: permission, membership or evidence ownership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractProblemResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareForbiddenResponse" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Collaboration - Comments" ], "summary": "CommentPost on a Sales Contract", "description": "Appends a plain-text comment. The client supplies a UUIDv7 id. Duplicate ids answer 409.", "operationId": "e3858c791deb2197a29e7a486cd1f691", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "contractId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "id", "body" ], "properties": { "parent_id": { "description": "Same-document comment; replies resolve to its root.", "type": "string", "format": "uuid", "nullable": true }, "id": { "type": "string", "format": "uuid", "example": "0190b7a0-1111-7222-8333-444455556666" }, "body": { "description": "Texto plano, incluidos los tokens @[Nombre](user:id); máximo 20 personas mencionadas", "type": "string", "example": "Need confirmation on the delivery window.", "maxLength": 5000 } }, "type": "object" } } } }, "responses": { "201": { "description": "Comment posted" }, "404": { "description": "Document or scoped evidence not found", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractProblemResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } ] } } } }, "409": { "description": "Duplicate comment ID", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "error_code": { "type": "string", "example": "comment_already_exists" } }, "type": "object" } } } }, "422": { "description": "Validación del texto o las menciones: máximo 5000 caracteres incluidos los tokens, 20 personas y solo miembros con vista; los rechazados se devuelven en rejected_user_ids", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollaborationCommentWriteProblem" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } } } }, "403": { "description": "Forbidden: permission, membership or evidence ownership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractProblemResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareForbiddenResponse" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/contract-activations/{activationId}/comments": { "get": { "tags": [ "Backoffice - Collaboration - Comments" ], "summary": "DocumentCommentsGet on a Sales Contract Activation", "description": "Returns every comment on the activación de contrato ordered by created_at ascending. `can_edit` / `can_delete` are computed for the authenticated actor.", "operationId": "aa2d4ca28fad7dd103312c88f9b6bf72", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "activationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Comment list", "content": { "application/json": { "schema": { "properties": { "items": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "body": { "type": "string" }, "author_user_id": { "type": "integer" }, "mentions": { "type": "array", "items": { "required": [ "user_id", "name" ], "properties": { "user_id": { "type": "integer" }, "name": { "type": "string" } }, "type": "object" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "edited_at": { "type": "string", "format": "date-time", "nullable": true }, "parent_id": { "type": "string", "format": "uuid", "nullable": true }, "is_deleted": { "type": "boolean" }, "can_edit": { "type": "boolean" }, "can_delete": { "type": "boolean" } }, "type": "object" } } }, "type": "object" } } } }, "404": { "description": "Document or scoped evidence not found", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractProblemResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } } } }, "403": { "description": "Forbidden: permission, membership or evidence ownership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractProblemResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareForbiddenResponse" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Collaboration - Comments" ], "summary": "CommentPost on a Sales Contract Activation", "description": "Appends a plain-text comment. The client supplies a UUIDv7 id. Duplicate ids answer 409.", "operationId": "dec5153fb3a55bbeed92ae17c8fa87aa", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "activationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "id", "body" ], "properties": { "parent_id": { "description": "Same-document comment; replies resolve to its root.", "type": "string", "format": "uuid", "nullable": true }, "id": { "type": "string", "format": "uuid", "example": "0190b7a0-1111-7222-8333-444455556666" }, "body": { "description": "Texto plano, incluidos los tokens @[Nombre](user:id); máximo 20 personas mencionadas", "type": "string", "example": "Need confirmation on the delivery window.", "maxLength": 5000 } }, "type": "object" } } } }, "responses": { "201": { "description": "Comment posted" }, "404": { "description": "Document or scoped evidence not found", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractProblemResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } ] } } } }, "409": { "description": "Duplicate comment ID", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "error_code": { "type": "string", "example": "comment_already_exists" } }, "type": "object" } } } }, "422": { "description": "Validación del texto o las menciones: máximo 5000 caracteres incluidos los tokens, 20 personas y solo miembros con vista; los rechazados se devuelven en rejected_user_ids", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollaborationCommentWriteProblem" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } } } }, "403": { "description": "Forbidden: permission, membership or evidence ownership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractProblemResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareForbiddenResponse" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/contract-deactivations/{deactivationId}/comments": { "get": { "tags": [ "Backoffice - Collaboration - Comments" ], "summary": "DocumentCommentsGet on a Sales Contract Deactivation", "description": "Returns every comment on the sales contract deactivation ordered by created_at ascending. `can_edit` / `can_delete` are computed for the authenticated actor.", "operationId": "3b87b0843acc6c9ccb21368d11b550b6", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "deactivationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Comment list", "content": { "application/json": { "schema": { "properties": { "items": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "body": { "type": "string" }, "author_user_id": { "type": "integer" }, "mentions": { "type": "array", "items": { "required": [ "user_id", "name" ], "properties": { "user_id": { "type": "integer" }, "name": { "type": "string" } }, "type": "object" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "edited_at": { "type": "string", "format": "date-time", "nullable": true }, "parent_id": { "type": "string", "format": "uuid", "nullable": true }, "is_deleted": { "type": "boolean" }, "can_edit": { "type": "boolean" }, "can_delete": { "type": "boolean" } }, "type": "object" } } }, "type": "object" } } } }, "404": { "description": "Document or scoped evidence not found", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractProblemResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } } } }, "403": { "description": "Forbidden: permission, membership or evidence ownership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractProblemResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareForbiddenResponse" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Collaboration - Comments" ], "summary": "CommentPost on a Sales Contract Deactivation", "description": "Appends a plain-text comment. The client supplies a UUIDv7 id. Duplicate ids answer 409.", "operationId": "43ff5a2afa6d833200218e84f7ad7656", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "deactivationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "id", "body" ], "properties": { "parent_id": { "description": "Same-document comment; replies resolve to its root.", "type": "string", "format": "uuid", "nullable": true }, "id": { "type": "string", "format": "uuid", "example": "0190b7a0-1111-7222-8333-444455556666" }, "body": { "description": "Texto plano, incluidos los tokens @[Nombre](user:id); máximo 20 personas mencionadas", "type": "string", "example": "Need confirmation on the delivery window.", "maxLength": 5000 } }, "type": "object" } } } }, "responses": { "201": { "description": "Comment posted" }, "404": { "description": "Document or scoped evidence not found", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractProblemResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } ] } } } }, "409": { "description": "Duplicate comment ID", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "error_code": { "type": "string", "example": "comment_already_exists" } }, "type": "object" } } } }, "422": { "description": "Validación del texto o las menciones: máximo 5000 caracteres incluidos los tokens, 20 personas y solo miembros con vista; los rechazados se devuelven en rejected_user_ids", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollaborationCommentWriteProblem" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } } } }, "403": { "description": "Forbidden: permission, membership or evidence ownership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractProblemResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareForbiddenResponse" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/items/{documentId}/comments": { "get": { "tags": [ "Backoffice - Inventory Items" ], "summary": "Get Item comments", "description": "Requires Item VIEW. Edit requires authorship; delete permits author or company admin. Foreign parent or mismatched child is 404.", "operationId": "e0892adb43a7d4a1ac85094dc948ed1b", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Comment collection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemComments" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemError" } } } }, "403": { "description": "Forbidden or tenant access refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemError" } } } }, "404": { "description": "Tenant-scoped resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemError" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Inventory Items" ], "summary": "Post Item comments", "description": "Requires Item VIEW. Edit requires authorship; delete permits author or company admin. Foreign parent or mismatched child is 404.", "operationId": "3c6eaeffc9baefe3d2c1019d5ac91ae2", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "id", "body" ], "properties": { "parent_id": { "description": "Same-document comment; replies resolve to its root.", "type": "string", "format": "uuid", "nullable": true }, "id": { "type": "string", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$" }, "body": { "description": "Texto plano, incluidos los tokens @[Nombre](user:id); máximo 20 personas mencionadas", "type": "string", "maxLength": 5000, "minLength": 1 } }, "type": "object" } } } }, "responses": { "201": { "description": "Created; empty JSON object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemEmptyResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemError" } } } }, "403": { "description": "Forbidden or tenant access refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemError" } } } }, "404": { "description": "Tenant-scoped resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemError" } } } }, "422": { "description": "Validación del texto o las menciones: máximo 5000 caracteres incluidos los tokens, 20 personas y solo miembros con vista; los rechazados se devuelven en rejected_user_ids", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollaborationCommentWriteProblem" } } } }, "409": { "description": "Comment identity already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemError" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/transfers/{documentId}/comments": { "get": { "tags": [ "Backoffice - Collaboration - Comments" ], "summary": "List comments on an inventory transfer (Traslado de inventario)", "description": "Returns every comment on the Traslado de inventario ordered by created_at ascending. `can_edit` / `can_delete` are computed for the authenticated actor.", "operationId": "8d7fdb6e8087976c3b1e80c3ccb812db", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Comment list", "content": { "application/json": { "schema": { "properties": { "items": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "body": { "type": "string" }, "author_user_id": { "type": "integer" }, "mentions": { "type": "array", "items": { "required": [ "user_id", "name" ], "properties": { "user_id": { "type": "integer" }, "name": { "type": "string" } }, "type": "object" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "edited_at": { "type": "string", "format": "date-time", "nullable": true }, "parent_id": { "type": "string", "format": "uuid", "nullable": true }, "is_deleted": { "type": "boolean" }, "can_edit": { "type": "boolean" }, "can_delete": { "type": "boolean" } }, "type": "object" } } }, "type": "object" } } } }, "404": { "description": "Document not found", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "error_code": { "type": "string", "example": "collaboration_document_not_found" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Collaboration - Comments" ], "summary": "Post a comment on an inventory transfer (Traslado de inventario)", "description": "Appends a plain-text comment. The client supplies a UUIDv7 id. Duplicate ids answer 409.", "operationId": "728bed44f3e7ec90755b9519cab3229d", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "id", "body" ], "properties": { "parent_id": { "description": "Same-document comment; replies resolve to its root.", "type": "string", "format": "uuid", "nullable": true }, "id": { "type": "string", "format": "uuid", "example": "0190b7a0-1111-7222-8333-444455556666" }, "body": { "description": "Texto plano, incluidos los tokens @[Nombre](user:id); máximo 20 personas mencionadas", "type": "string", "example": "Need confirmation on the delivery window.", "maxLength": 5000 } }, "type": "object" } } } }, "responses": { "201": { "description": "Comment posted" }, "404": { "description": "Document not found", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "error_code": { "type": "string", "example": "collaboration_document_not_found" } }, "type": "object" } } } }, "409": { "description": "Duplicate comment ID", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "error_code": { "type": "string", "example": "comment_already_exists" } }, "type": "object" } } } }, "422": { "description": "Validación del texto o las menciones: máximo 5000 caracteres incluidos los tokens, 20 personas y solo miembros con vista; los rechazados se devuelven en rejected_user_ids", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollaborationCommentWriteProblem" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/treasury/transfers/{documentId}/comments": { "get": { "tags": [ "Backoffice - Collaboration - Comments" ], "summary": "List comments on a treasury transfer (transferencia entre cuentas propias)", "description": "Returns every comment on the transferencia entre cuentas propias ordered by created_at ascending. `can_edit` / `can_delete` are computed for the authenticated actor. Requires `backoffice.treasury.treasury-transfers.view`.", "operationId": "42630238d85b32adf6d9a8f9111d7ce2", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Comment list", "content": { "application/json": { "schema": { "properties": { "items": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "body": { "type": "string" }, "author_user_id": { "type": "integer" }, "mentions": { "type": "array", "items": { "required": [ "user_id", "name" ], "properties": { "user_id": { "type": "integer" }, "name": { "type": "string" } }, "type": "object" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "edited_at": { "type": "string", "format": "date-time", "nullable": true }, "parent_id": { "type": "string", "format": "uuid", "nullable": true }, "is_deleted": { "type": "boolean" }, "can_edit": { "type": "boolean" }, "can_delete": { "type": "boolean" } }, "type": "object" } } }, "type": "object" } } } }, "404": { "description": "Document not found", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "error_code": { "type": "string", "example": "collaboration_document_not_found" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Collaboration - Comments" ], "summary": "Post a comment on a treasury transfer (transferencia entre cuentas propias)", "description": "Appends a plain-text comment. The client supplies a UUIDv7 id. Duplicate ids answer 409. Requires `backoffice.treasury.treasury-transfers.view`.", "operationId": "70980081b754c350951a9ce60528af74", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "id", "body" ], "properties": { "parent_id": { "description": "Same-document comment; replies resolve to its root.", "type": "string", "format": "uuid", "nullable": true }, "id": { "type": "string", "format": "uuid", "example": "0190b7a0-1111-7222-8333-444455556666" }, "body": { "description": "Texto plano, incluidos los tokens @[Nombre](user:id); máximo 20 personas mencionadas", "type": "string", "example": "Need confirmation on the delivery window.", "maxLength": 5000 } }, "type": "object" } } } }, "responses": { "201": { "description": "Comment posted" }, "404": { "description": "Document not found", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "error_code": { "type": "string", "example": "collaboration_document_not_found" } }, "type": "object" } } } }, "409": { "description": "Duplicate comment ID", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "error_code": { "type": "string", "example": "comment_already_exists" } }, "type": "object" } } } }, "422": { "description": "Validación del texto o las menciones: máximo 5000 caracteres incluidos los tokens, 20 personas y solo miembros con vista; los rechazados se devuelven en rejected_user_ids", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollaborationCommentWriteProblem" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/dispatches/{documentId}/comments": { "get": { "tags": [ "Backoffice - Collaboration - Comments" ], "summary": "List comments on an inventory dispatch (Despacho de inventario)", "description": "Returns every comment on the Despacho de inventario ordered by created_at ascending. `can_edit` / `can_delete` are computed for the authenticated actor.", "operationId": "42dc227bf440bef888aa913f05fe932d", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Comment list", "content": { "application/json": { "schema": { "properties": { "items": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "body": { "type": "string" }, "author_user_id": { "type": "integer" }, "mentions": { "type": "array", "items": { "required": [ "user_id", "name" ], "properties": { "user_id": { "type": "integer" }, "name": { "type": "string" } }, "type": "object" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "edited_at": { "type": "string", "format": "date-time", "nullable": true }, "parent_id": { "type": "string", "format": "uuid", "nullable": true }, "is_deleted": { "type": "boolean" }, "can_edit": { "type": "boolean" }, "can_delete": { "type": "boolean" } }, "type": "object" } } }, "type": "object" } } } }, "404": { "description": "HTTP 404; document, child and company scope are enforced", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/InventoryDispatchProblem" }, { "$ref": "#/components/schemas/InventoryDispatchUnauthenticated" } ] } } } }, "401": { "description": "HTTP 401; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryDispatchUnauthenticated" } } } }, "403": { "description": "HTTP 403; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryDispatchForbidden" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Collaboration - Comments" ], "summary": "Post a comment on an inventory dispatch (Despacho de inventario)", "description": "Appends a plain-text comment. The client supplies a UUIDv7 id. Duplicate ids answer 409.", "operationId": "b6b5de92fb67b5781382e3768b5979fa", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "id", "body" ], "properties": { "parent_id": { "description": "Same-document comment; replies resolve to its root.", "type": "string", "format": "uuid", "nullable": true }, "id": { "type": "string", "format": "uuid", "example": "0190b7a0-1111-7222-8333-444455556666" }, "body": { "description": "Texto plano, incluidos los tokens @[Nombre](user:id); máximo 20 personas mencionadas", "type": "string", "example": "Need confirmation on the delivery window.", "maxLength": 5000 } }, "type": "object" } } } }, "responses": { "201": { "description": "Empty JSON object acknowledgement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryDispatchAcknowledgement" } } } }, "404": { "description": "HTTP 404; document, child and company scope are enforced", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/InventoryDispatchProblem" }, { "$ref": "#/components/schemas/InventoryDispatchUnauthenticated" } ] } } } }, "409": { "description": "HTTP 409; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryDispatchProblem" } } } }, "422": { "description": "Validación del texto o las menciones: máximo 5000 caracteres incluidos los tokens, 20 personas y solo miembros con vista; los rechazados se devuelven en rejected_user_ids", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollaborationCommentWriteProblem" } } } }, "401": { "description": "HTTP 401; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryDispatchUnauthenticated" } } } }, "403": { "description": "HTTP 403; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryDispatchForbidden" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/entries/{documentId}/comments": { "get": { "tags": [ "Backoffice - Collaboration - Comments" ], "summary": "List comments on an inventory entry (Entrada de inventario)", "description": "Returns every comment on the Entrada de inventario ordered by created_at ascending. `can_edit` / `can_delete` are computed for the authenticated actor.", "operationId": "04f2cf804f985c13ec4802f5069e10fc", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Comment list", "content": { "application/json": { "schema": { "properties": { "items": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "body": { "type": "string" }, "author_user_id": { "type": "integer" }, "mentions": { "type": "array", "items": { "required": [ "user_id", "name" ], "properties": { "user_id": { "type": "integer" }, "name": { "type": "string" } }, "type": "object" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "edited_at": { "type": "string", "format": "date-time", "nullable": true }, "parent_id": { "type": "string", "format": "uuid", "nullable": true }, "is_deleted": { "type": "boolean" }, "can_edit": { "type": "boolean" }, "can_delete": { "type": "boolean" } }, "type": "object" } } }, "type": "object" } } } }, "404": { "description": "HTTP 404; document, child and company scope are enforced", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/InventoryEntryProblem" }, { "$ref": "#/components/schemas/InventoryEntryUnauthenticated" } ] } } } }, "401": { "description": "HTTP 401; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryEntryUnauthenticated" } } } }, "403": { "description": "HTTP 403; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryEntryForbidden" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Collaboration - Comments" ], "summary": "Post a comment on an inventory entry (Entrada de inventario)", "description": "Appends a plain-text comment. The client supplies a UUIDv7 id. Duplicate ids answer 409.", "operationId": "51756c3e6a0a16c45341793de6ab0c3f", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "id", "body" ], "properties": { "parent_id": { "description": "Same-document comment; replies resolve to its root.", "type": "string", "format": "uuid", "nullable": true }, "id": { "type": "string", "format": "uuid", "example": "0190b7a0-1111-7222-8333-444455556666" }, "body": { "description": "Texto plano, incluidos los tokens @[Nombre](user:id); máximo 20 personas mencionadas", "type": "string", "example": "Need confirmation on the delivery window.", "maxLength": 5000 } }, "type": "object" } } } }, "responses": { "201": { "description": "Empty JSON object acknowledgement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryEntryAcknowledgement" } } } }, "404": { "description": "HTTP 404; document, child and company scope are enforced", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/InventoryEntryProblem" }, { "$ref": "#/components/schemas/InventoryEntryUnauthenticated" } ] } } } }, "409": { "description": "HTTP 409; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryEntryProblem" } } } }, "422": { "description": "Validación del texto o las menciones: máximo 5000 caracteres incluidos los tokens, 20 personas y solo miembros con vista; los rechazados se devuelven en rejected_user_ids", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollaborationCommentWriteProblem" } } } }, "401": { "description": "HTTP 401; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryEntryUnauthenticated" } } } }, "403": { "description": "HTTP 403; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryEntryForbidden" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/transformations/{documentId}/comments": { "get": { "tags": [ "Backoffice - Collaboration - Comments" ], "summary": "List comments on a transformation (Transformación de ítems)", "description": "Returns every comment on the Transformación de ítems ordered by created_at ascending. `can_edit` / `can_delete` are computed for the authenticated actor.", "operationId": "4ed2d80aed85be8a79693a1831849199", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Comment list", "content": { "application/json": { "schema": { "properties": { "items": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "body": { "type": "string" }, "author_user_id": { "type": "integer" }, "mentions": { "type": "array", "items": { "required": [ "user_id", "name" ], "properties": { "user_id": { "type": "integer" }, "name": { "type": "string" } }, "type": "object" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "edited_at": { "type": "string", "format": "date-time", "nullable": true }, "parent_id": { "type": "string", "format": "uuid", "nullable": true }, "is_deleted": { "type": "boolean" }, "can_edit": { "type": "boolean" }, "can_delete": { "type": "boolean" } }, "type": "object" } } }, "type": "object" } } } }, "404": { "description": "HTTP 404; document, child and company scope are enforced", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/TransformationProblem" }, { "$ref": "#/components/schemas/TransformationUnauthenticated" } ] } } } }, "401": { "description": "HTTP 401; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransformationUnauthenticated" } } } }, "403": { "description": "HTTP 403; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransformationForbidden" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Collaboration - Comments" ], "summary": "Post a comment on a transformation (Transformación de ítems)", "description": "Appends a plain-text comment. The client supplies a UUIDv7 id. Duplicate ids answer 409.", "operationId": "75d345a6dd978bd77daa9a889ab5b27a", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "id", "body" ], "properties": { "parent_id": { "description": "Same-document comment; replies resolve to its root.", "type": "string", "format": "uuid", "nullable": true }, "id": { "type": "string", "format": "uuid", "example": "0190b7a0-1111-7222-8333-444455556666" }, "body": { "description": "Texto plano, incluidos los tokens @[Nombre](user:id); máximo 20 personas mencionadas", "type": "string", "example": "Need confirmation on the delivery window.", "maxLength": 5000 } }, "type": "object" } } } }, "responses": { "201": { "description": "Empty JSON object acknowledgement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransformationAcknowledgement" } } } }, "404": { "description": "HTTP 404; document, child and company scope are enforced", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/TransformationProblem" }, { "$ref": "#/components/schemas/TransformationUnauthenticated" } ] } } } }, "409": { "description": "HTTP 409; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransformationProblem" } } } }, "422": { "description": "Validación del texto o las menciones: máximo 5000 caracteres incluidos los tokens, 20 personas y solo miembros con vista; los rechazados se devuelven en rejected_user_ids", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollaborationCommentWriteProblem" } } } }, "401": { "description": "HTTP 401; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransformationUnauthenticated" } } } }, "403": { "description": "HTTP 403; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransformationForbidden" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/adjustments/{documentId}/comments": { "get": { "tags": [ "Backoffice - Collaboration - Comments" ], "summary": "List comments on an inventory adjustment (Ajuste de inventario)", "description": "Returns every comment on the Ajuste de inventario ordered by created_at ascending. `can_edit` / `can_delete` are computed for the authenticated actor.", "operationId": "db89237739d119e982121598b1fa76f2", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Comment list", "content": { "application/json": { "schema": { "properties": { "items": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "body": { "type": "string" }, "author_user_id": { "type": "integer" }, "mentions": { "type": "array", "items": { "required": [ "user_id", "name" ], "properties": { "user_id": { "type": "integer" }, "name": { "type": "string" } }, "type": "object" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "edited_at": { "type": "string", "format": "date-time", "nullable": true }, "parent_id": { "type": "string", "format": "uuid", "nullable": true }, "is_deleted": { "type": "boolean" }, "can_edit": { "type": "boolean" }, "can_delete": { "type": "boolean" } }, "type": "object" } } }, "type": "object" } } } }, "404": { "description": "HTTP 404; document, child and company scope are enforced", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/AdjustmentProblem" }, { "$ref": "#/components/schemas/AdjustmentUnauthenticated" } ] } } } }, "401": { "description": "HTTP 401; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdjustmentUnauthenticated" } } } }, "403": { "description": "HTTP 403; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdjustmentForbidden" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Collaboration - Comments" ], "summary": "Post a comment on an inventory adjustment (Ajuste de inventario)", "description": "Appends a plain-text comment. The client supplies a UUIDv7 id. Duplicate ids answer 409.", "operationId": "cc627a3e303c29dbc10752e6d8ac62e9", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "id", "body" ], "properties": { "parent_id": { "description": "Same-document comment; replies resolve to its root.", "type": "string", "format": "uuid", "nullable": true }, "id": { "type": "string", "format": "uuid", "example": "0190b7a0-1111-7222-8333-444455556666" }, "body": { "description": "Texto plano, incluidos los tokens @[Nombre](user:id); máximo 20 personas mencionadas", "type": "string", "example": "Need confirmation on the delivery window.", "maxLength": 5000 } }, "type": "object" } } } }, "responses": { "201": { "description": "Empty JSON object acknowledgement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdjustmentAcknowledgement" } } } }, "404": { "description": "HTTP 404; document, child and company scope are enforced", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/AdjustmentProblem" }, { "$ref": "#/components/schemas/AdjustmentUnauthenticated" } ] } } } }, "409": { "description": "HTTP 409; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdjustmentProblem" } } } }, "422": { "description": "Validación del texto o las menciones: máximo 5000 caracteres incluidos los tokens, 20 personas y solo miembros con vista; los rechazados se devuelven en rejected_user_ids", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollaborationCommentWriteProblem" } } } }, "401": { "description": "HTTP 401; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdjustmentUnauthenticated" } } } }, "403": { "description": "HTTP 403; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdjustmentForbidden" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/credit-notes/{documentId}/comments": { "get": { "tags": [ "Backoffice - Collaboration - Comments" ], "summary": "List comments on a supplier nota de crédito de proveedor", "description": "Requires `backoffice.purchases.credit-notes.view`. Returns every comment ordered by created_at ascending. `can_edit` / `can_delete` are computed for the authenticated actor.", "operationId": "e9b1a5b51753751a5b95169ab11f331a", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Comment list", "content": { "application/json": { "schema": { "properties": { "items": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "body": { "type": "string" }, "author_user_id": { "type": "integer" }, "mentions": { "type": "array", "items": { "required": [ "user_id", "name" ], "properties": { "user_id": { "type": "integer" }, "name": { "type": "string" } }, "type": "object" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "edited_at": { "type": "string", "format": "date-time", "nullable": true }, "parent_id": { "type": "string", "format": "uuid", "nullable": true }, "is_deleted": { "type": "boolean" }, "can_edit": { "type": "boolean" }, "can_delete": { "type": "boolean" } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks backoffice.purchases.credit-notes.view" }, "404": { "description": "Document not found" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Collaboration - Comments" ], "summary": "Post a comment on a supplier nota de crédito de proveedor", "description": "Requires `backoffice.purchases.credit-notes.view`. Appends a plain-text comment. The client supplies a UUIDv7 id. Duplicate ids answer 409.", "operationId": "d5e60409d2217a457ad383f6752dfe80", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "id", "body" ], "properties": { "parent_id": { "description": "Same-document comment; replies resolve to its root.", "type": "string", "format": "uuid", "nullable": true }, "id": { "type": "string", "format": "uuid" }, "body": { "description": "Texto plano, incluidos los tokens @[Nombre](user:id); máximo 20 personas mencionadas", "type": "string", "maxLength": 5000 } }, "type": "object" } } } }, "responses": { "201": { "description": "Comment created" }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks backoffice.purchases.credit-notes.view" }, "404": { "description": "Document not found" }, "409": { "description": "Duplicate comment ID" }, "422": { "description": "Validación del texto o las menciones: máximo 5000 caracteres incluidos los tokens, 20 personas y solo miembros con vista; los rechazados se devuelven en rejected_user_ids", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollaborationCommentWriteProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/debit-notes/{documentId}/comments": { "get": { "tags": [ "Backoffice - Collaboration - Comments" ], "summary": "List comments on a supplier nota de débito de proveedor", "description": "Requires `backoffice.purchases.debit-notes.view`. Returns every comment ordered by created_at ascending. `can_edit` / `can_delete` are computed for the authenticated actor.", "operationId": "6e708fb6b49e471723a964d9089cf435", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Comment list", "content": { "application/json": { "schema": { "properties": { "items": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "body": { "type": "string" }, "author_user_id": { "type": "integer" }, "mentions": { "type": "array", "items": { "required": [ "user_id", "name" ], "properties": { "user_id": { "type": "integer" }, "name": { "type": "string" } }, "type": "object" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "edited_at": { "type": "string", "format": "date-time", "nullable": true }, "parent_id": { "type": "string", "format": "uuid", "nullable": true }, "is_deleted": { "type": "boolean" }, "can_edit": { "type": "boolean" }, "can_delete": { "type": "boolean" } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks backoffice.purchases.debit-notes.view" }, "404": { "description": "Document not found" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Collaboration - Comments" ], "summary": "Post a comment on a supplier nota de débito de proveedor", "description": "Requires `backoffice.purchases.debit-notes.view`. Appends a plain-text comment. The client supplies a UUIDv7 id. Duplicate ids answer 409.", "operationId": "2105757edeeacd4051b338656e2e1e03", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "id", "body" ], "properties": { "parent_id": { "description": "Same-document comment; replies resolve to its root.", "type": "string", "format": "uuid", "nullable": true }, "id": { "type": "string", "format": "uuid" }, "body": { "description": "Texto plano, incluidos los tokens @[Nombre](user:id); máximo 20 personas mencionadas", "type": "string", "maxLength": 5000 } }, "type": "object" } } } }, "responses": { "201": { "description": "Comment created" }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks backoffice.purchases.debit-notes.view" }, "404": { "description": "Document not found" }, "409": { "description": "Duplicate comment ID" }, "422": { "description": "Validación del texto o las menciones: máximo 5000 caracteres incluidos los tokens, 20 personas y solo miembros con vista; los rechazados se devuelven en rejected_user_ids", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollaborationCommentWriteProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/collaboration/{type}/{id}/followers": { "get": { "tags": [ "Backoffice - Collaboration - Followers" ], "summary": "List active document followers", "operationId": "400a9338bb6e6a8b5b7ac8fc99f6beab", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "type", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "required": [ "user_id", "reason", "active" ], "properties": { "user_id": { "type": "integer" }, "reason": { "type": "string", "enum": [ "responsible", "commented", "mentioned", "manual" ] }, "active": { "type": "boolean" } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Membership or module view permission required" }, "404": { "description": "Document not found" }, "422": { "description": "Invalid document type" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/collaboration/{type}/{id}/follow": { "post": { "tags": [ "Backoffice - Collaboration - Followers" ], "summary": "Follow a document", "operationId": "9e692b9f9eb4f70bcd2b5fafabe9fb4f", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "type", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Membership or module view permission required" }, "404": { "description": "Document not found" }, "422": { "description": "Invalid document type" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Backoffice - Collaboration - Followers" ], "summary": "Stop following a document", "operationId": "815246485f64b682ed49a7260ad3e9bf", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "type", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Success" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Membership or module view permission required" }, "404": { "description": "Document not found" }, "422": { "description": "Invalid document type" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/collections/{documentId}/labels/{labelId}": { "put": { "tags": [ "Backoffice - Collaboration - Label Assignments" ], "summary": "Assign a label on a collection", "description": "Requires collections.update; document and label must belong to this company.", "operationId": "7c1ba7a70ca4d38c8f54269ebd364155", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "labelId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Idempotent label assignment change" }, "404": { "description": "Collection or label not found" }, "422": { "description": "Invalid label assignment" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Backoffice - Collaboration - Label Assignments" ], "summary": "Unassign a label on a collection", "description": "Requires collections.update; document and label must belong to this company.", "operationId": "22b15456fa035448bc3b4e0172276c85", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "labelId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Idempotent label assignment change" }, "404": { "description": "Collection or label not found" }, "422": { "description": "Invalid label assignment" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/orders/{documentId}/labels/{labelId}": { "put": { "tags": [ "Backoffice - Collaboration - Label Assignments" ], "summary": "Assign a label to a purchase order (Pedido)", "description": "Idempotent assign. Returns 204 whether newly assigned or already present.", "operationId": "252fcd04c7b309781764492ad8880257", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "labelId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Label assigned (or already present)" }, "404": { "description": "Document or label not found" }, "422": { "description": "Label is archived" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Backoffice - Collaboration - Label Assignments" ], "summary": "Unassign a label from a purchase order (Pedido)", "description": "Idempotent unassign. Returns 204 whether removed or already absent.", "operationId": "a2100e62424178da099fda7fe8894746", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "labelId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Label unassigned (or already absent)" }, "404": { "description": "Document not found" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/purchases-orders/{documentId}/labels/{labelId}": { "put": { "tags": [ "Backoffice - Collaboration - Label Assignments" ], "summary": "Assign a label to a purchase order (Orden de compra)", "description": "Idempotent assign. Returns 204 whether newly assigned or already present.", "operationId": "9e07c11d1adc951365ec9e1c003df05c", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "labelId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Label assigned (or already present)" }, "404": { "description": "Document or label not found" }, "422": { "description": "Label is archived" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Backoffice - Collaboration - Label Assignments" ], "summary": "Unassign a label from a purchase order (Orden de compra)", "description": "Idempotent unassign. Returns 204 whether removed or already absent.", "operationId": "fd54bb14b704297492f29dee877db4db", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "labelId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Label unassigned (or already absent)" }, "404": { "description": "Document not found" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/providers/{documentId}/labels/{labelId}": { "put": { "tags": [ "Backoffice - Collaboration - Label Assignments" ], "summary": "Assign a label to a provider", "description": "Requires `backoffice.purchases.providers.update`. Idempotent assign. Returns 204 whether newly assigned or already present.", "operationId": "2879168ad99a0a7fb28729fd4b63f25c", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "labelId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Label assigned (or already present)" }, "404": { "description": "Document or label not found" }, "422": { "description": "Label is archived" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Backoffice - Collaboration - Label Assignments" ], "summary": "Unassign a label from a provider", "description": "Requires `backoffice.purchases.providers.update`. Idempotent unassign. Returns 204 whether removed or already absent.", "operationId": "37ee4d77c2dc2d9b7a3946407ced37e7", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "labelId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Label unassigned (or already absent)" }, "404": { "description": "Document not found" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/sales-invoices/{documentId}/labels/{labelId}": { "put": { "tags": [ "Backoffice - Collaboration - Label Assignments" ], "summary": "Assign a label to a sales invoice", "description": "Idempotent assign. Returns 204 whether newly assigned or already present.", "operationId": "7f84cba2db63a72ce85a8897c06fdf8a", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "labelId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Label assigned (or already present)" }, "404": { "description": "Document or label not found, or a path id that is not a UUID, which the router answers before the controller with a `message` body.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/LabelAssignmentProblem" }, { "$ref": "#/components/schemas/LabelAssignmentMiddlewareMessage" } ] } } } }, "422": { "description": "Label is archived", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LabelAssignmentProblem" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LabelAssignmentMiddlewareMessage" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LabelAssignmentProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Backoffice - Collaboration - Label Assignments" ], "summary": "Unassign a label from a sales invoice", "description": "Idempotent unassign. Returns 204 whether removed or already absent.", "operationId": "c5bcb06555fe121e0001b3f0c8fb083c", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "labelId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Label unassigned (or already absent)" }, "404": { "description": "Document not found, or a path id that is not a UUID, which the router answers before the controller with a `message` body.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/LabelAssignmentProblem" }, { "$ref": "#/components/schemas/LabelAssignmentMiddlewareMessage" } ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LabelAssignmentMiddlewareMessage" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LabelAssignmentProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/sales-orders/{documentId}/labels/{labelId}": { "put": { "tags": [ "Backoffice - Collaboration - Label Assignments" ], "summary": "Assign a label to a sales order", "description": "Idempotent assign. Returns 204 whether newly assigned or already present.", "operationId": "ee2e20125ce8dff28ddacc81b9e928ce", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "labelId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Label assigned (or already present)" }, "404": { "description": "Document or label not found" }, "422": { "description": "Label is archived" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Backoffice - Collaboration - Label Assignments" ], "summary": "Unassign a label from a sales order", "description": "Idempotent unassign. Returns 204 whether removed or already absent.", "operationId": "681b7823a34f607c2b62b90005c091db", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "labelId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Label unassigned (or already absent)" }, "404": { "description": "Document not found" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/contracts/{documentId}/labels/{labelId}": { "put": { "tags": [ "Backoffice - Collaboration - Label Assignments" ], "summary": "DocumentLabelPut on a Purchase Contract", "description": "Idempotent assign. Returns 204 whether newly assigned or already present.", "operationId": "eb7b619cc1b3428191a65dd4ef639d3b", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "labelId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Label assigned (or already present)" }, "404": { "description": "Document or scoped evidence not found", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } ] } } } }, "422": { "description": "Request validation or domain validation error", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractValidationError" } ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } } } }, "403": { "description": "Forbidden: permission, membership or evidence ownership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Backoffice - Collaboration - Label Assignments" ], "summary": "DocumentLabelDelete on a Purchase Contract", "description": "Idempotent unassign. Returns 204 whether removed or already absent.", "operationId": "5ee04df9bda242b7932ac72a9d9a9092", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "labelId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Label unassigned (or already absent)" }, "404": { "description": "Document or scoped evidence not found", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } } } }, "403": { "description": "Forbidden: permission, membership or evidence ownership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/contract-activations/{documentId}/labels/{labelId}": { "put": { "tags": [ "Backoffice - Collaboration - Label Assignments" ], "summary": "DocumentLabelPut on a Purchase Contract Activation", "description": "Idempotent assign. Returns 204 whether newly assigned or already present.", "operationId": "54d3348357030af2be4463a04cf52713", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "labelId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Label assigned (or already present)" }, "404": { "description": "Document or scoped evidence not found", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } ] } } } }, "422": { "description": "Request validation or domain validation error", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractValidationError" } ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } } } }, "403": { "description": "Forbidden: permission, membership or evidence ownership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Backoffice - Collaboration - Label Assignments" ], "summary": "DocumentLabelDelete on a Purchase Contract Activation", "description": "Idempotent unassign. Returns 204 whether removed or already absent.", "operationId": "5b17581937aedea38f0ee294ccb3a0bb", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "labelId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Label unassigned (or already absent)" }, "404": { "description": "Document or scoped evidence not found", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } } } }, "403": { "description": "Forbidden: permission, membership or evidence ownership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/contract-addenda/{documentId}/labels/{labelId}": { "put": { "tags": [ "Backoffice - Collaboration - Label Assignments" ], "summary": "DocumentLabelPut on a Purchase Contract Addendum", "description": "Idempotent assign. Returns 204 whether newly assigned or already present.", "operationId": "66abd2ad83878e97f12ba4628c65668c", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "labelId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Label assigned (or already present)" }, "404": { "description": "Document or scoped evidence not found", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } ] } } } }, "422": { "description": "Request validation or domain validation error", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractValidationError" } ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } } } }, "403": { "description": "Forbidden: permission, membership or evidence ownership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Backoffice - Collaboration - Label Assignments" ], "summary": "DocumentLabelDelete on a Purchase Contract Addendum", "description": "Idempotent unassign. Returns 204 whether removed or already absent.", "operationId": "f817522ba6bd8309a153b14f8bd20547", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "labelId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Label unassigned (or already absent)" }, "404": { "description": "Document or scoped evidence not found", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } } } }, "403": { "description": "Forbidden: permission, membership or evidence ownership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/contract-deactivations/{documentId}/labels/{labelId}": { "put": { "tags": [ "Backoffice - Collaboration - Label Assignments" ], "summary": "DocumentLabelPut on a Purchase Contract Deactivation", "description": "Idempotent assign. Returns 204 whether newly assigned or already present.", "operationId": "cc5d58fefe3ed739fcd4cf11f7aa5a93", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "labelId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Label assigned (or already present)" }, "404": { "description": "Document or scoped evidence not found", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } ] } } } }, "422": { "description": "Request validation or domain validation error", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractValidationError" } ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } } } }, "403": { "description": "Forbidden: permission, membership or evidence ownership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Backoffice - Collaboration - Label Assignments" ], "summary": "DocumentLabelDelete on a Purchase Contract Deactivation", "description": "Idempotent unassign. Returns 204 whether removed or already absent.", "operationId": "263ab205fc0d836fdbb37d7449e07f84", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "labelId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Label unassigned (or already absent)" }, "404": { "description": "Document or scoped evidence not found", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } } } }, "403": { "description": "Forbidden: permission, membership or evidence ownership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/contracts/{contractId}/labels/{labelId}": { "put": { "tags": [ "Backoffice - Collaboration - Label Assignments" ], "summary": "DocumentLabelPut on a Sales Contract", "description": "Idempotent assign. Returns 204 whether newly assigned or already present.", "operationId": "62ff502fb73e6cdc99d6a4ce1d8bea89", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "contractId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "labelId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Label assigned (or already present)" }, "404": { "description": "Document or scoped evidence not found", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractProblemResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } ] } } } }, "422": { "description": "Request validation or domain validation error", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractProblemResponse" }, { "$ref": "#/components/schemas/ContractRequestValidationResponse" } ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } } } }, "403": { "description": "Forbidden: permission, membership or evidence ownership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractProblemResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareForbiddenResponse" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Backoffice - Collaboration - Label Assignments" ], "summary": "DocumentLabelDelete on a Sales Contract", "description": "Idempotent unassign. Returns 204 whether removed or already absent.", "operationId": "852ee62a55f6b5942f2ae8c65f205418", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "contractId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "labelId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Label unassigned (or already absent)" }, "404": { "description": "Document or scoped evidence not found", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractProblemResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } } } }, "403": { "description": "Forbidden: permission, membership or evidence ownership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractProblemResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareForbiddenResponse" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/contract-activations/{activationId}/labels/{labelId}": { "put": { "tags": [ "Backoffice - Collaboration - Label Assignments" ], "summary": "DocumentLabelPut on a Sales Contract Activation", "description": "Idempotent assign. Returns 204 whether newly assigned or already present.", "operationId": "5989e811774f68ec807c391157038143", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "activationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "labelId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Label assigned (or already present)" }, "404": { "description": "Document or scoped evidence not found", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractProblemResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } ] } } } }, "422": { "description": "Request validation or domain validation error", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractProblemResponse" }, { "$ref": "#/components/schemas/ContractRequestValidationResponse" } ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } } } }, "403": { "description": "Forbidden: permission, membership or evidence ownership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractProblemResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareForbiddenResponse" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Backoffice - Collaboration - Label Assignments" ], "summary": "DocumentLabelDelete on a Sales Contract Activation", "description": "Idempotent unassign. Returns 204 whether removed or already absent.", "operationId": "096efd58a5666f2cd0760c305df7f8ed", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "activationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "labelId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Label unassigned (or already absent)" }, "404": { "description": "Document or scoped evidence not found", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractProblemResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } } } }, "403": { "description": "Forbidden: permission, membership or evidence ownership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractProblemResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareForbiddenResponse" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/contract-deactivations/{deactivationId}/labels/{labelId}": { "put": { "tags": [ "Backoffice - Collaboration - Label Assignments" ], "summary": "DocumentLabelPut on a Sales Contract Deactivation", "description": "Idempotent assign. Returns 204 whether newly assigned or already present.", "operationId": "2b512edad522caa71ccc9da458107f45", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "deactivationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "labelId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Label assigned (or already present)" }, "404": { "description": "Document or scoped evidence not found", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractProblemResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } ] } } } }, "422": { "description": "Request validation or domain validation error", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractProblemResponse" }, { "$ref": "#/components/schemas/ContractRequestValidationResponse" } ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } } } }, "403": { "description": "Forbidden: permission, membership or evidence ownership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractProblemResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareForbiddenResponse" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Backoffice - Collaboration - Label Assignments" ], "summary": "DocumentLabelDelete on a Sales Contract Deactivation", "description": "Idempotent unassign. Returns 204 whether removed or already absent.", "operationId": "e3207309ad3099427e8ed2f0de7fa4e9", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "deactivationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "labelId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Label unassigned (or already absent)" }, "404": { "description": "Document or scoped evidence not found", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractProblemResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } } } }, "403": { "description": "Forbidden: permission, membership or evidence ownership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractProblemResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareForbiddenResponse" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/potential-customers/{potentialCustomerId}/labels/{labelId}": { "put": { "tags": [ "Backoffice - Collaboration - Label Assignments" ], "summary": "DocumentLabelPut on a Potential Customer", "description": "Idempotent assign. Returns 204 whether newly assigned or already present.", "operationId": "2dd6a59589981f2965ff0c394483e686", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "potentialCustomerId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "labelId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Label assigned (or already present)" }, "404": { "description": "Document or scoped evidence not found", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractProblemResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } ] } } } }, "422": { "description": "Request validation or domain validation error", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractProblemResponse" }, { "$ref": "#/components/schemas/ContractRequestValidationResponse" } ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } } } }, "403": { "description": "Forbidden: permission, membership or evidence ownership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractProblemResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareForbiddenResponse" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Backoffice - Collaboration - Label Assignments" ], "summary": "DocumentLabelDelete on a Potential Customer", "description": "Idempotent unassign. Returns 204 whether removed or already absent.", "operationId": "c1cbcd558627d01fb1bbe58142d664f7", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "potentialCustomerId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "labelId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Label unassigned (or already absent)" }, "404": { "description": "Document or scoped evidence not found", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractProblemResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } } } }, "403": { "description": "Forbidden: permission, membership or evidence ownership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractProblemResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareForbiddenResponse" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/transfers/{documentId}/labels/{labelId}": { "put": { "tags": [ "Backoffice - Collaboration - Label Assignments" ], "summary": "Assign a label to an inventory transfer (Traslado de inventario)", "description": "Idempotent assign. Returns 204 whether newly assigned or already present.", "operationId": "84e6336c8e5ba5a8d77b4bd24b0c64ed", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "labelId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Label assigned (or already present)" }, "404": { "description": "Document or label not found" }, "422": { "description": "Label is archived" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Backoffice - Collaboration - Label Assignments" ], "summary": "Unassign a label from an inventory transfer (Traslado de inventario)", "description": "Idempotent unassign. Returns 204 whether removed or already absent.", "operationId": "dc48e6fda21872531a4854a8876cb5cd", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "labelId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Label unassigned (or already absent)" }, "404": { "description": "Document not found" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/treasury/transfers/{documentId}/labels/{labelId}": { "put": { "tags": [ "Backoffice - Collaboration - Label Assignments" ], "summary": "Assign a label to a treasury transfer (transferencia entre cuentas propias)", "description": "Idempotent assign. Returns 204 whether newly assigned or already present. Requires `backoffice.treasury.treasury-transfers.manage`.", "operationId": "9029585f07491f636e42f7b12caa70b6", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "labelId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Label assigned (or already present)" }, "404": { "description": "Document or label not found" }, "422": { "description": "Label is archived" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Backoffice - Collaboration - Label Assignments" ], "summary": "Unassign a label from a treasury transfer (transferencia entre cuentas propias)", "description": "Idempotent unassign. Returns 204 whether removed or already absent. Requires `backoffice.treasury.treasury-transfers.manage`.", "operationId": "fb133e5e792097a94a0b22e2759c7ca7", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "labelId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Label unassigned (or already absent)" }, "404": { "description": "Document not found" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/dispatches/{documentId}/labels/{labelId}": { "put": { "tags": [ "Backoffice - Collaboration - Label Assignments" ], "summary": "Assign a label to an inventory dispatch (Despacho de inventario)", "description": "Idempotent assign. Returns 204 whether newly assigned or already present.", "operationId": "5326b7f575fad4e188b890de7d8af67e", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "labelId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Label assigned (or already present)" }, "404": { "description": "HTTP 404; document, child and company scope are enforced", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/InventoryDispatchProblem" }, { "$ref": "#/components/schemas/InventoryDispatchUnauthenticated" } ] } } } }, "422": { "description": "HTTP 422; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryDispatchProblem" } } } }, "401": { "description": "HTTP 401; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryDispatchUnauthenticated" } } } }, "403": { "description": "HTTP 403; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryDispatchForbidden" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Backoffice - Collaboration - Label Assignments" ], "summary": "Unassign a label from an inventory dispatch (Despacho de inventario)", "description": "Idempotent unassign. Returns 204 whether removed or already absent.", "operationId": "ef43e01693c53f2ca6bca33791b0e299", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "labelId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Label unassigned (or already absent)" }, "404": { "description": "HTTP 404; document, child and company scope are enforced", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/InventoryDispatchProblem" }, { "$ref": "#/components/schemas/InventoryDispatchUnauthenticated" } ] } } } }, "401": { "description": "HTTP 401; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryDispatchUnauthenticated" } } } }, "403": { "description": "HTTP 403; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryDispatchForbidden" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/entries/{documentId}/labels/{labelId}": { "put": { "tags": [ "Backoffice - Collaboration - Label Assignments" ], "summary": "Assign a label to an inventory entry (Entrada de inventario)", "description": "Idempotent assign. Returns 204 whether newly assigned or already present.", "operationId": "8ebc7b237923066381c644567c52145f", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "labelId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Label assigned (or already present)" }, "404": { "description": "HTTP 404; document, child and company scope are enforced", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/InventoryEntryProblem" }, { "$ref": "#/components/schemas/InventoryEntryUnauthenticated" } ] } } } }, "422": { "description": "HTTP 422; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryEntryProblem" } } } }, "401": { "description": "HTTP 401; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryEntryUnauthenticated" } } } }, "403": { "description": "HTTP 403; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryEntryForbidden" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Backoffice - Collaboration - Label Assignments" ], "summary": "Unassign a label from an inventory entry (Entrada de inventario)", "description": "Idempotent unassign. Returns 204 whether removed or already absent.", "operationId": "4c49f02f41b4e969e13b64da100ec7cf", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "labelId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Label unassigned (or already absent)" }, "404": { "description": "HTTP 404; document, child and company scope are enforced", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/InventoryEntryProblem" }, { "$ref": "#/components/schemas/InventoryEntryUnauthenticated" } ] } } } }, "401": { "description": "HTTP 401; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryEntryUnauthenticated" } } } }, "403": { "description": "HTTP 403; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryEntryForbidden" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/transformations/{documentId}/labels/{labelId}": { "put": { "tags": [ "Backoffice - Collaboration - Label Assignments" ], "summary": "Assign a label to a transformation (Transformación de ítems)", "description": "Idempotent assign. Returns 204 whether newly assigned or already present.", "operationId": "375e036be11d0f64c5ad0055b295aae3", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "labelId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Label assigned (or already present)" }, "404": { "description": "HTTP 404; document, child and company scope are enforced", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/TransformationProblem" }, { "$ref": "#/components/schemas/TransformationUnauthenticated" } ] } } } }, "422": { "description": "HTTP 422; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransformationProblem" } } } }, "401": { "description": "HTTP 401; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransformationUnauthenticated" } } } }, "403": { "description": "HTTP 403; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransformationForbidden" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Backoffice - Collaboration - Label Assignments" ], "summary": "Unassign a label from a transformation (Transformación de ítems)", "description": "Idempotent unassign. Returns 204 whether removed or already absent.", "operationId": "ccac8df9c96bf22fac5d538da2a3e9d5", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "labelId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Label unassigned (or already absent)" }, "404": { "description": "HTTP 404; document, child and company scope are enforced", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/TransformationProblem" }, { "$ref": "#/components/schemas/TransformationUnauthenticated" } ] } } } }, "401": { "description": "HTTP 401; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransformationUnauthenticated" } } } }, "403": { "description": "HTTP 403; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransformationForbidden" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/adjustments/{documentId}/labels/{labelId}": { "put": { "tags": [ "Backoffice - Collaboration - Label Assignments" ], "summary": "Assign a label to an inventory adjustment (Ajuste de inventario)", "description": "Idempotent assign. Returns 204 whether newly assigned or already present.", "operationId": "e0d7a7b4b4ce294fc74b8b8c65a6f4d3", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "labelId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Label assigned (or already present)" }, "404": { "description": "HTTP 404; document, child and company scope are enforced", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/AdjustmentProblem" }, { "$ref": "#/components/schemas/AdjustmentUnauthenticated" } ] } } } }, "422": { "description": "HTTP 422; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdjustmentProblem" } } } }, "401": { "description": "HTTP 401; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdjustmentUnauthenticated" } } } }, "403": { "description": "HTTP 403; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdjustmentForbidden" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Backoffice - Collaboration - Label Assignments" ], "summary": "Unassign a label from an inventory adjustment (Ajuste de inventario)", "description": "Idempotent unassign. Returns 204 whether removed or already absent.", "operationId": "382b8f0bdb0ece7c34db6f35c337b4e0", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "labelId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Label unassigned (or already absent)" }, "404": { "description": "HTTP 404; document, child and company scope are enforced", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/AdjustmentProblem" }, { "$ref": "#/components/schemas/AdjustmentUnauthenticated" } ] } } } }, "401": { "description": "HTTP 401; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdjustmentUnauthenticated" } } } }, "403": { "description": "HTTP 403; document, child and company scope are enforced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdjustmentForbidden" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/credit-notes/{documentId}/labels/{labelId}": { "put": { "tags": [ "Backoffice - Collaboration - Label Assignments" ], "summary": "Assign a label to a supplier credit note", "description": "Requires `backoffice.purchases.credit-notes.create`. Idempotent assign. Returns 204 whether newly assigned or already present.", "operationId": "9a00eb92f6fbf31eac7ddbdbd3582d09", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "labelId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Label assigned (or already present)" }, "404": { "description": "Document or label not found", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/LabelAssignmentProblem" }, { "$ref": "#/components/schemas/LabelAssignmentMiddlewareMessage" } ] } } } }, "422": { "description": "Label is archived", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LabelAssignmentProblem" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LabelAssignmentMiddlewareMessage" } } } }, "403": { "description": "The user lacks backoffice.purchases.credit-notes.create", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LabelAssignmentProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Backoffice - Collaboration - Label Assignments" ], "summary": "Unassign a label from a supplier credit note", "description": "Requires `backoffice.purchases.credit-notes.create`. Idempotent unassign. Returns 204 whether removed or already absent.", "operationId": "06730ed8e90bfdb71a9d3b9719a2f830", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "labelId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Label unassigned (or already absent)" }, "404": { "description": "Document not found", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/LabelAssignmentProblem" }, { "$ref": "#/components/schemas/LabelAssignmentMiddlewareMessage" } ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LabelAssignmentMiddlewareMessage" } } } }, "403": { "description": "The user lacks backoffice.purchases.credit-notes.create", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LabelAssignmentProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/debit-notes/{documentId}/labels/{labelId}": { "put": { "tags": [ "Backoffice - Collaboration - Label Assignments" ], "summary": "Assign a label to a supplier debit note", "description": "Requires `backoffice.purchases.debit-notes.create`. Idempotent assign. Returns 204 whether newly assigned or already present.", "operationId": "91cdc64b81068d3cf97a90e5fbca1b52", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "labelId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Label assigned (or already present)" }, "404": { "description": "Document or label not found", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/LabelAssignmentProblem" }, { "$ref": "#/components/schemas/LabelAssignmentMiddlewareMessage" } ] } } } }, "422": { "description": "Label is archived", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LabelAssignmentProblem" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LabelAssignmentMiddlewareMessage" } } } }, "403": { "description": "The user lacks backoffice.purchases.debit-notes.create", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LabelAssignmentProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Backoffice - Collaboration - Label Assignments" ], "summary": "Unassign a label from a supplier debit note", "description": "Requires `backoffice.purchases.debit-notes.create`. Idempotent unassign. Returns 204 whether removed or already absent.", "operationId": "c3c700798360d02b0b77298e944552d4", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "labelId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Label unassigned (or already absent)" }, "404": { "description": "Document not found", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/LabelAssignmentProblem" }, { "$ref": "#/components/schemas/LabelAssignmentMiddlewareMessage" } ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LabelAssignmentMiddlewareMessage" } } } }, "403": { "description": "The user lacks backoffice.purchases.debit-notes.create", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LabelAssignmentProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/items/{documentId}/labels/{labelId}": { "put": { "tags": [ "Backoffice - Inventory Items" ], "summary": "Assign an Item label", "description": "Requires Item UPDATE; label and parent must belong to the route company.", "operationId": "f3f2f633d16e5c4d61b397c1b58d7d45", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "labelId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Assigned or already assigned" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemError" } } } }, "403": { "description": "Forbidden or tenant access refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemError" } } } }, "404": { "description": "Tenant-scoped resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemError" } } } }, "422": { "description": "Label is archived", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemError" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Backoffice - Inventory Items" ], "summary": "Unassign an Item label", "description": "Requires Item UPDATE. Missing or foreign label and parent are 404; a valid company label with no assignment remains an idempotent 204.", "operationId": "677f1d407fe161339e76ab75742b5834", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "labelId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Removed or valid label already unassigned" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemError" } } } }, "403": { "description": "Forbidden or tenant access refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemError" } } } }, "404": { "description": "Tenant-scoped resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemError" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/labels/{id}/archive": { "put": { "tags": [ "Backoffice - Collaboration - Labels" ], "summary": "Archive a company label", "operationId": "0efb8382e1576ff4e393cc3654e99936", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Label archived" }, "404": { "description": "Label not found" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/labels": { "get": { "tags": [ "Backoffice - Collaboration - Labels" ], "summary": "List company labels (catalog lookup)", "description": "Membership-gated lookup projection. Default excludes archived labels; pass include_archived=true or 1 to include them.", "operationId": "31a7d9b958179b9e87435529bc0d6043", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "include_archived", "in": "query", "required": false, "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Label catalog items", "content": { "application/json": { "schema": { "properties": { "items": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "tone": { "type": "string", "enum": [ "red", "orange", "blue", "violet", "teal" ] }, "archived": { "type": "boolean" } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Collaboration - Labels" ], "summary": "Create a company label", "operationId": "a4134adb9844df468f82d2dbe644c8e2", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "id", "name", "tone" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "0190b7a0-1111-7222-8333-444455556666" }, "name": { "type": "string", "example": "Urgente", "maxLength": 40 }, "tone": { "type": "string", "example": "red", "enum": [ "red", "orange", "blue", "violet", "teal" ] } }, "type": "object" } } } }, "responses": { "201": { "description": "Label created" }, "409": { "description": "Duplicate id or name" }, "422": { "description": "Validation error" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/labels/{id}": { "put": { "tags": [ "Backoffice - Collaboration - Labels" ], "summary": "Update a company label name and/or tone", "operationId": "b3be89d2638927efcf2cc4e73e2a5c40", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "name": { "type": "string", "maxLength": 40 }, "tone": { "type": "string", "enum": [ "red", "orange", "blue", "violet", "teal" ] } }, "type": "object" } } } }, "responses": { "200": { "description": "Label updated" }, "404": { "description": "Label not found" }, "409": { "description": "Duplicate name" }, "422": { "description": "Validation error" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/labels/{id}/restore": { "put": { "tags": [ "Backoffice - Collaboration - Labels" ], "summary": "Restore an archived company label", "operationId": "0b8c5f810fc119d31d4b9e98918a1292", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Label restored" }, "404": { "description": "Label not found" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/collaboration/mentionable-users": { "get": { "tags": [ "Backoffice - Collaboration" ], "summary": "Lookup active members who can view the document type, excluding the acting user", "description": "Membership-only lookup; filters by literal name substring. Permission filtering precedes pagination.", "operationId": "ccbe2fa0b2123ff0332a062928372aef", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "document_type", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "PotentialCustomer", "Contract", "ContractActivation", "ContractDeactivation", "Provider", "Item", "InventoryTransfer", "InventoryDispatch", "InventoryEntry", "Transformation", "Adjustment", "Client", "Order", "PurchaseOrder", "PurchasesInvoice", "PurchaseCreditNote", "PurchaseDebitNote", "Payment", "PurchaseContract", "PurchaseContractActivation", "PurchaseContractAddendum", "PurchaseContractDeactivation", "Collection", "SalesInvoice", "SalesOrder", "SalesQuote", "BankReconciliation", "TaxDeclaration", "TreasuryTransfer" ] } }, { "name": "search", "in": "query", "description": "Name substring; blank means no filter; LIKE wildcards are literal.", "required": false, "schema": { "type": "string", "maxLength": 200 } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 200, "minimum": 1 } } ], "responses": { "200": { "description": "Eligible members, ordered by name and id", "content": { "application/json": { "schema": { "required": [ "items", "total", "per_page", "current_page" ], "properties": { "items": { "type": "array", "items": { "required": [ "id", "name" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "type": "object", "additionalProperties": false } }, "total": { "type": "integer" }, "per_page": { "type": "integer" }, "current_page": { "type": "integer" } }, "type": "object", "additionalProperties": false } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Not an active company member" }, "404": { "description": "Company not found" }, "422": { "description": "Invalid query", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string" }, "error_code": { "type": "string", "nullable": true }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inbox": { "get": { "tags": [ "Backoffice - Inbox" ], "summary": "List personal notification groups", "operationId": "54cd4f4be3166717dbe3f58fa91ead8a", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "filter", "in": "query", "schema": { "type": "string", "default": "unread", "enum": [ "unread", "all" ] } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxPage" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Inactive or non-member" }, "404": { "description": "Company or owned group not found" }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inbox/unread-count": { "get": { "tags": [ "Backoffice - Inbox" ], "summary": "Count visible unread document groups", "operationId": "35252e64a0cdb21b7de24cd126788719", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxCounts" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Inactive or non-member" }, "404": { "description": "Company or owned group not found" }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inbox/groups/{documentType}/{documentId}/read": { "post": { "tags": [ "Backoffice - Inbox" ], "summary": "Mark group read", "operationId": "840f6ae63a1fd9f2eedd4532f6d758d5", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "documentType", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Inactive or non-member" }, "404": { "description": "Company or owned group not found" }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inbox/groups/{documentType}/{documentId}/unread": { "post": { "tags": [ "Backoffice - Inbox" ], "summary": "Mark group unread", "operationId": "8fa5174f622ef2c544e8dc9333b2f8bc", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "documentType", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Inactive or non-member" }, "404": { "description": "Company or owned group not found" }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inbox/groups/{documentType}/{documentId}/delete": { "post": { "tags": [ "Backoffice - Inbox" ], "summary": "Mark group delete", "operationId": "cb6b82c923b818f0d4fa3726ce443382", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "documentType", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "required": [ "undo_token" ], "properties": { "undo_token": { "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Inactive or non-member" }, "404": { "description": "Company or owned group not found" }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inbox/groups/{documentType}/{documentId}/restore": { "post": { "tags": [ "Backoffice - Inbox" ], "summary": "Mark group restore", "operationId": "3910798f38ac31b8585066256d011b6f", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "documentType", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Inactive or non-member" }, "404": { "description": "Company or owned group not found" }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inbox/groups/{documentType}/{documentId}/snooze": { "post": { "tags": [ "Backoffice - Inbox" ], "summary": "Mark group snooze", "operationId": "da310ab4d7a3a7554987a8205c26e538", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "documentType", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "until" ], "properties": { "until": { "description": "Future ISO8601 instant with explicit timezone", "type": "string", "format": "date-time" } }, "type": "object" } } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Inactive or non-member" }, "404": { "description": "Company or owned group not found" }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inbox/groups/{documentType}/{documentId}/unsnooze": { "post": { "tags": [ "Backoffice - Inbox" ], "summary": "Mark group unsnooze", "operationId": "d3b3fd65944a839cc21da3af80f43373", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "documentType", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Inactive or non-member" }, "404": { "description": "Company or owned group not found" }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inbox/read-all": { "post": { "tags": [ "Backoffice - Inbox" ], "summary": "read-all", "operationId": "b123de8bf09c3850dbf431308dc4c970", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Inactive or non-member" }, "404": { "description": "Company or owned group not found" }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inbox/restore-read": { "post": { "tags": [ "Backoffice - Inbox" ], "summary": "Restore the exact notifications deleted by this recipient, within ten minutes", "operationId": "d617054c7f60a63cf1731e2b608abd82", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "undo_token" ], "properties": { "undo_token": { "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Inactive or non-member" }, "404": { "description": "Company or owned group not found" }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inbox/delete-read": { "post": { "tags": [ "Backoffice - Inbox" ], "summary": "delete-read", "operationId": "8be0da3fddc041147d8a785605828855", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "required": [ "undo_token" ], "properties": { "undo_token": { "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Inactive or non-member" }, "404": { "description": "Company or owned group not found" }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/notifications/email-unsubscribe/{userId}/{companyId}": { "get": { "tags": [ "Notification preferences" ], "summary": "Show a signed unsubscribe confirmation without changing preferences", "operationId": "9511aec6846312676d9632ded3483445", "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } }, { "name": "companyId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "signature", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTML confirmation form; GET has no side effects" }, "403": { "description": "Laravel signature middleware rejects missing or altered signatures" } }, "security": [] }, "post": { "tags": [ "Notification preferences" ], "summary": "RFC 8058 signed one-click unsubscribe from every email category", "operationId": "6d27bfcde95280a8ed399253fc06ac1c", "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } }, { "name": "companyId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "signature", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTML confirmation with link to notification preferences; repeated POST is idempotent" }, "403": { "description": "Laravel signature middleware rejects missing or altered signatures" } }, "security": [] } }, "/api/backoffice/{tenant}/me/notification-preferences": { "get": { "tags": [ "Notification preferences" ], "summary": "Read the authenticated user email preferences across companies", "operationId": "3d37a687f771f5aa3625fae8a9d7760e", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Enabled defaults when no saved preference row exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationPreferences" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Company membership required" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Notification preferences" ], "summary": "Save the authenticated user email preferences across companies", "operationId": "883f5129ffc3a9b0b88fe27f67ec378d", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationPreferences" } } } }, "responses": { "200": { "description": "Saved preferences; Bandeja delivery is unaffected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationPreferences" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Company membership required" }, "422": { "description": "Controller-rendered validation Problem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationPreferencesValidationProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/companies/{id}/feature-flags": { "get": { "tags": [ "Backoffice - Companies" ], "summary": "Get feature flags for a company", "operationId": "78d19be0bf93c1e536775af8c6f33360", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Feature flags payload", "content": { "application/json": { "schema": { "properties": { "company_id": { "type": "string", "format": "uuid" }, "pnl_dashboard_enabled": { "type": "boolean" }, "assistant_enabled": { "type": "boolean" } }, "type": "object" } } } }, "403": { "description": "Forbidden" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/book-currencies": { "get": { "tags": [ "Backoffice - Companies - Book Currencies" ], "summary": "Get the currencies of the company's books and its timezone", "description": "The functional and reporting currencies of the Company's books, plus its Timezone so screens date documents on the Company's calendar day. Requires tenant membership only, never backoffice.companies.view: screens of every module read it, whatever role their authors hold (ADR 0018).", "operationId": "getBookCurrencies", "parameters": [ { "name": "tenant", "in": "path", "description": "Company (tenant) ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Currencies of the company's functional and reporting books, and its timezone", "content": { "application/json": { "schema": { "required": [ "functional_currency", "reporting_currency", "timezone", "number_format" ], "properties": { "number_format": { "type": "string", "enum": [ "es_VE", "en" ] }, "functional_currency": { "description": "ISO 4217 currency of the company's functional book", "type": "string", "example": "VES" }, "reporting_currency": { "description": "ISO 4217 currency of the company's reporting book", "type": "string", "example": "USD" }, "timezone": { "description": "IANA timezone of the company, whose calendar day dates its documents", "type": "string", "example": "America/Caracas" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated (Laravel Sanctum)", "content": { "application/json": { "schema": { "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "403": { "description": "Forbidden, always answered by middleware: tenant membership adds a reason; company access and API-key guardrails send only title, status and detail", "content": { "application/json": { "schema": { "required": [ "title", "status", "detail" ], "properties": { "title": { "type": "string", "example": "Forbidden" }, "status": { "type": "integer", "example": 403 }, "detail": { "type": "string", "example": "You do not have access to this company" }, "reason": { "type": "string", "example": "DENIED_NO_MEMBERSHIP" } }, "type": "object" } } } }, "404": { "description": "Unknown tenant or API key bound to another company (middleware message), or company not found (controller Problem)", "content": { "application/json": { "schema": { "oneOf": [ { "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Recurso no encontrado" } }, "type": "object" }, { "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "detail": { "type": "string" }, "error_code": { "type": "string", "example": "company_not_found", "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true } }, "type": "object" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/company-capabilities": { "get": { "tags": [ "Backoffice - Companies - Capabilities" ], "summary": "Get the company's capabilities and whether its fiscal profile is configured", "description": "The capabilities the Company's country enables (the Company Fiscal Profile and the bank-name suggestion directory), whether its fiscal profile is configured and, when it is, the issuance channel the document forms read. It never includes the RIF, the legal name, the fiscal address, the Active Control Series or the country: the fiscal settings page and the company record read those from GET /companies/{id}. Requires tenant membership only, never backoffice.companies.view: screens of every module read it, whatever role their authors hold (ADR 0018).", "operationId": "getCompanyCapabilities", "parameters": [ { "name": "tenant", "in": "path", "description": "Company (tenant) ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The company's capabilities and the summary of its fiscal profile", "content": { "application/json": { "schema": { "required": [ "capabilities", "fiscal_profile", "free_form_notice" ], "properties": { "free_form_notice": { "description": "Server-derived warning only for an active free_form profile; null for all other channels. Days use the company calendar.", "properties": { "days_remaining": { "type": "integer", "minimum": 0 }, "message": { "type": "string" } }, "type": "object", "nullable": true }, "capabilities": { "required": [ "fiscal_profile", "bank_directory" ], "properties": { "fiscal_profile": { "description": "Whether the company's country enables the Company Fiscal Profile.", "type": "boolean", "example": true }, "bank_directory": { "description": "Bank-name suggestion directory for the company's country; null when none.", "type": "string", "example": "VE", "nullable": true, "enum": [ "VE" ] } }, "type": "object" }, "fiscal_profile": { "required": [ "configured", "issuance_channel" ], "properties": { "configured": { "description": "Whether the country enables the Company Fiscal Profile and the company has defined one; never null.", "type": "boolean", "example": true }, "issuance_channel": { "description": "How the company issues its fiscal documents; null whenever configured is false.", "type": "string", "example": "fiscal_machine", "nullable": true, "enum": [ "fiscal_machine", "free_form", "digital_printer", "seniat_portal" ] } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated (Laravel Sanctum)", "content": { "application/json": { "schema": { "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "403": { "description": "Forbidden, always answered by middleware: tenant membership adds a reason; company access and API-key guardrails send only title, status and detail", "content": { "application/json": { "schema": { "required": [ "title", "status", "detail" ], "properties": { "title": { "type": "string", "example": "Forbidden" }, "status": { "type": "integer", "example": 403 }, "detail": { "type": "string", "example": "You do not have access to this company" }, "reason": { "type": "string", "example": "DENIED_NO_MEMBERSHIP" } }, "type": "object" } } } }, "404": { "description": "Unknown tenant or API key bound to another company (middleware message), or company not found (controller Problem)", "content": { "application/json": { "schema": { "oneOf": [ { "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Recurso no encontrado" } }, "type": "object" }, { "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "detail": { "type": "string" }, "error_code": { "type": "string", "example": "company_not_found", "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true } }, "type": "object" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/companies": { "get": { "tags": [ "Backoffice - Companies" ], "summary": "List the companies the user belongs to", "description": "Only the session user's companies, sorted by name and then id. Values are ORed within status and ANDed across fields. meta.counts drops only the status filter and is zero-filled. Unknown parameters, user_id among them, are ignored. A search with no match is an empty page. The flat total, per_page and current_page keys repeat meta.", "operationId": "0c58c513067577d717aae607fbf2218f", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "search", "in": "query", "description": "The name contains this text, ignoring case; % and _ match literally. An empty value does not filter.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "name", "in": "query", "description": "Same match as search, ANDed with it; use search.", "deprecated": true, "schema": { "type": "string", "maxLength": 255 } }, { "name": "status[]", "in": "query", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "ACTIVE", "INACTIVE" ] } } }, { "name": "status", "in": "query", "description": "Scalar alias of status[]; all or an empty value does not filter.", "schema": { "type": "string", "enum": [ "ACTIVE", "INACTIVE", "all" ] } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompaniesPage" } } } }, "403": { "description": "HTTP 403; needs backoffice.companies.view", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyProblem" } } } }, "422": { "description": "HTTP 422; errors names the parameter, status.0 for a status[] item", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyProblem" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Internal Server Error" }, "status": { "type": "integer", "example": 500 }, "detail": { "type": "string", "example": "An unexpected error occurred" } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Companies" ], "summary": "Create a new company", "operationId": "77d6e58ec2719b6df2983c0214f0aca0", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "id", "name" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426655440000" }, "name": { "type": "string", "example": "MedineTech", "maxLength": 80, "minLength": 3 }, "number_format": { "type": "string", "default": "es_VE", "enum": [ "es_VE", "en" ] }, "country": { "type": "string", "example": "VE", "nullable": true }, "timezone": { "type": "string", "example": "America/Caracas", "nullable": true }, "functional_currency": { "type": "string", "example": "USD", "nullable": true }, "reporting_currency": { "type": "string", "example": "USD", "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Company created successfully" }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unauthorized" }, "status": { "type": "integer", "example": 403 }, "detail": { "type": "string", "example": "You do not have permission to view this resource." } }, "type": "object" } } } }, "409": { "description": "The id belongs to an existing company (`company_already_exists`); nothing is changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyProblem" } } } }, "422": { "description": "Invalid request: a validation failure (`detail` `The given data was invalid.`, `error_code` null, field-keyed `errors`, e.g. `errors.name` for a name outside 3–80 characters) or a refused profile (`error_code` such as `invalid_country`, `errors` null)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyProblem" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Internal Server Error" }, "status": { "type": "integer", "example": 500 }, "detail": { "type": "string", "example": "An unexpected error occurred while processing your request." } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/companies/{id}/fiscal-profile": { "get": { "tags": [ "Companies" ], "summary": "Read the current company fiscal settings without Companies permission", "operationId": "fc6cb2645a69672f3070d09de2262ad8", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Fiscal settings projection", "content": { "application/json": { "schema": { "required": [ "timezone", "capabilities", "fiscal_profile" ], "properties": { "timezone": { "type": "string" }, "capabilities": { "required": [ "fiscal_profile" ], "properties": { "fiscal_profile": { "type": "boolean" } }, "type": "object" }, "fiscal_profile": { "properties": { "rif": { "type": "string" }, "legal_name": { "type": "string" }, "fiscal_address": { "type": "string" }, "issuance_channel": { "type": "string" }, "active_control_series": { "type": "string", "nullable": true } }, "type": "object", "nullable": true } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Missing fiscal-settings.view or tenant membership" }, "404": { "description": "Company is not the path tenant or does not exist" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Backoffice - Companies" ], "summary": "Define the company's fiscal profile", "description": "Saves the Company Fiscal Profile as a whole (RIF, legal name, fiscal address, issuance channel, and optionally the Active Control Series). From the PA 00093 effective day in the company timezone, saving free_form returns 422 free_form_issuance_expired, including unchanged profiles. Other unchanged profiles return 200 and record nothing. The response body is empty: read GET /companies/{id} for the canonical values. `{id}` must be the path tenant. Validation order: format (422), country capability (422), RIF uniqueness across tenants (409). An API key needs the `write` ability.", "operationId": "c5a64b4273dcfebb90b93610bf45e6c1", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "The company whose profile is defined. Must equal {tenant}; any other value returns 404 once the body is well-formed.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "rif", "legal_name", "fiscal_address", "issuance_channel" ], "properties": { "rif": { "description": "Letter V, E, J, P or G, 8 digits and a modulo-11 check digit; hyphens optional, case-insensitive. Stored as L-NNNNNNNN-D. A wrong check digit returns 422 invalid_rif.", "type": "string", "example": "J-12345678-4", "maxLength": 12, "minLength": 1 }, "legal_name": { "description": "Trimmed, with every whitespace run collapsed into one space; 1 to 255 characters after that.", "type": "string", "example": "Inversiones Ejemplo, C.A.", "maxLength": 255, "minLength": 1 }, "fiscal_address": { "description": "Trimmed, with every whitespace run (newlines included) collapsed into one space; 1 to 500 characters after that.", "type": "string", "example": "Av. Francisco de Miranda, Torre Parque Cristal, Caracas", "maxLength": 500, "minLength": 1 }, "issuance_channel": { "type": "string", "example": "fiscal_machine", "enum": [ "fiscal_machine", "free_form", "digital_printer", "seniat_portal" ] }, "active_control_series": { "description": "Optional. The prefix of the control numbers the company prints today (`00` in `00-00012345`), the source of the proposed control number. Trimmed and uppercased, then 1 to 10 letters or digits. Leaving the key out keeps the current series; sending null or an empty string clears it.", "type": "string", "pattern": "^[A-Za-z0-9]{1,10}$", "example": "00", "nullable": true, "maxLength": 10, "minLength": 1 } }, "type": "object" } } } }, "responses": { "200": { "description": "Profile defined, or unchanged", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "Missing backoffice.accounting.settings.fiscal-settings.update, or a read-only API key (api_key_write_ability_required)", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Forbidden" }, "status": { "type": "integer", "example": 403 }, "detail": { "type": "string", "example": "You do not have permission to access this resource." } }, "type": "object" } } } }, "404": { "description": "company_not_found: {id} is not the path tenant, or the company does not exist", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "error_code": { "type": "string", "example": "company_not_found" } }, "type": "object" } } } }, "409": { "description": "rif_not_available: another company holds the RIF. The message never names it.", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "detail": { "type": "string", "example": "Este RIF no está disponible; si te pertenece, contacta a soporte" }, "error_code": { "type": "string", "example": "rif_not_available" } }, "type": "object" } } } }, "422": { "description": "Either an `errors` map keyed by field with a null `error_code` (shape validation), or a domain `error_code` with a null `errors`", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string", "example": "El RIF no es válido" }, "error_code": { "type": "string", "nullable": true, "enum": [ "invalid_rif", "invalid_legal_name", "invalid_fiscal_address", "invalid_issuance_channel", "invalid_control_series", "fiscal_profile_not_enabled" ] }, "errors": { "type": "object", "nullable": true } }, "type": "object" } } } }, "429": { "description": "Too many attempts: 10 per minute per user" }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Internal Server Error" }, "status": { "type": "integer", "example": 500 }, "detail": { "type": "string", "example": "An Unexpected Error Occurred" } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/companies/{id}": { "get": { "tags": [ "Backoffice - Companies" ], "summary": "Get a company by ID", "description": "Returns the details of a company based on the provided ID. `{id}` must equal the path tenant (otherwise 404). `capabilities` is always present. `fiscal_profile` is null while the company has not defined its Company Fiscal Profile.", "operationId": "8ce2fdc6a4d6b3e9565080ac09e8b091", "parameters": [ { "name": "id", "in": "path", "description": "The ID of the company to retrieve", "required": true, "schema": { "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426655440000" } } ], "responses": { "200": { "description": "Company details retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyRecord" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unauthorized" }, "status": { "type": "integer", "example": 403 }, "detail": { "type": "string", "example": "You do not have permission to view this resource." } }, "type": "object" } } } }, "404": { "description": "Company not found (including when {id} does not match the path tenant)", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Company not found" }, "status": { "type": "integer", "example": 404 }, "detail": { "type": "string", "example": "La empresa con el id 123e4567-e89b-12d3-a456-426655440000 no existe" } }, "type": "object" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Internal Server Error" }, "status": { "type": "integer", "example": 500 }, "detail": { "type": "string", "example": "An unexpected error occurred." } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Backoffice - Companies" ], "summary": "Update an existing company", "operationId": "774f02f6c5438876c4512464fc9b5fa4", "parameters": [ { "name": "id", "in": "path", "description": "The ID of the company to update", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name" ], "properties": { "number_format": { "type": "string", "enum": [ "es_VE", "en" ] }, "name": { "type": "string", "example": "New Company Name", "maxLength": 80, "minLength": 3 } }, "type": "object" } } } }, "responses": { "200": { "description": "Company updated successfully" }, "422": { "description": "Validation failure: `detail` `The given data was invalid.`, `error_code` null and field-keyed `errors`, e.g. `errors.name` for a name outside 3–80 characters. Checked after the path tenant, so another company's id answers 404 first.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyProblem" } } } }, "404": { "description": "Company not found (including when {id} does not match the path tenant)", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "detail": { "type": "string", "example": "La empresa con el id 123e4567-e89b-12d3-a456-426655440000 no existe" } }, "type": "object" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unauthorized" }, "status": { "type": "integer", "example": 403 }, "detail": { "type": "string", "example": "You do not have permission to view this resource." } }, "type": "object" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Error" }, "status": { "type": "integer", "example": 500 }, "detail": { "type": "string", "example": "An unexpected error occurred while processing your request." } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/subscription/owner-confirmation": { "post": { "tags": [ "Subscriptions" ], "summary": "An active company Superadmin explicitly confirms their operational ownership", "operationId": "182c04c27375235c677cbf7118c84bcf", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "confirmed", "reason" ], "properties": { "confirmed": { "type": "boolean", "enum": [ true ] }, "reason": { "type": "string", "maxLength": 500, "minLength": 10 } }, "type": "object" } } } }, "responses": { "201": { "description": "Confirmed, or an idempotent replay by the same owner" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Not an active company Superadmin" }, "404": { "description": "Unknown company" }, "409": { "description": "No ownership confirmation pending" }, "422": { "description": "Missing attestation or invalid reference" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/me/defaults": { "get": { "tags": [ "Company user defaults" ], "summary": "Get the authenticated user defaults in this company", "operationId": "17b499c9fd16a34edd297358814bf97a", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Company-scoped personal proposals", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyUserDefaults" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Membership required" }, "422": { "description": "Invalid or inactive/foreign catalog choice" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Company user defaults" ], "summary": "Put the authenticated user defaults in this company", "operationId": "5504d6d9faafffec6d696f725f9554a7", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyUserDefaults" } } } }, "responses": { "200": { "description": "Company-scoped personal proposals", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyUserDefaults" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Membership required" }, "422": { "description": "Invalid or inactive/foreign catalog choice" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/company-users/lookup": { "get": { "tags": [ "Backoffice - Company User Lookups" ], "summary": "Lookup Company users for tenant forms", "operationId": "30c61a134d25767bae99396f6b6abf33", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 200, "minimum": 1 } }, { "name": "perPage", "in": "query", "description": "Compatibility alias for per_page", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 200, "minimum": 1 } }, { "name": "search", "in": "query", "description": "Case-insensitive substring match on the member name. A blank value applies no filter. LIKE wildcards are matched literally.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Minimal Company user projection", "content": { "application/json": { "schema": { "required": [ "items", "total", "per_page", "current_page" ], "properties": { "items": { "type": "array", "items": { "required": [ "id", "name", "status" ], "properties": { "id": { "type": "integer", "example": 7 }, "name": { "type": "string", "example": "Ana Perez" }, "status": { "type": "string", "enum": [ "active", "inactive" ] } }, "type": "object", "additionalProperties": false } }, "total": { "type": "integer" }, "per_page": { "type": "integer" }, "current_page": { "type": "integer" } }, "type": "object", "additionalProperties": false } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Authenticated but not a member of this tenant" }, "404": { "description": "Tenant not found" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/subscription/onboarding": { "get": { "tags": [ "Backoffice - First Companies" ], "summary": "Read basic setup and provisioning state", "description": "Read-only persisted state. Returns no billing PII and never starts provisioning.", "operationId": "008efd6ca5a516858991056f9145267b", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Current state including not_started before answers exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicSetupState" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicSetupMessage" } } } }, "403": { "description": "Company access or membership denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicSetupAccessDenied" } } } }, "409": { "description": "Email unverified", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/BasicSetupUnverifiedEmail" }, { "$ref": "#/components/schemas/BasicSetupMessage" } ] } } } }, "500": { "description": "Unexpected read failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicSetupProblem" } } } } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Backoffice - First Companies" ], "summary": "Complete the basic setup for a self-registered company", "description": "Persists billing answers separately from the Company's own fiscal profile. Canonically identical submissions retry preparation only while preparing. Provisioning runs synchronously after commit; a captured provisioning failure returns 200 preparing. Changed answers return basic_setup_already_completed; missing signup provenance returns basic_setup_registration_required.", "operationId": "4c9de69fcd7e12c29203e8d09aa417f1", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "what_sells", "document_type", "document_number", "legal_name", "fiscal_address" ], "properties": { "what_sells": { "type": "string", "enum": [ "products", "services", "both" ] }, "document_type": { "type": "string", "enum": [ "rif", "cedula" ] }, "document_number": { "description": "RIF with validated checksum or Venezuelan cédula; existing canonical input tolerance applies.", "type": "string", "example": "J-00000000-0", "minLength": 1 }, "legal_name": { "description": "Required nonblank text; whitespace collapsed before character limits.", "type": "string", "maxLength": 255, "minLength": 1 }, "fiscal_address": { "description": "Required nonblank text; whitespace collapsed before character limits.", "type": "string", "maxLength": 500, "minLength": 1 } }, "type": "object" } } } }, "responses": { "200": { "description": "Answers saved; provisioning ready or preparing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicSetupState" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicSetupMessage" } } } }, "403": { "description": "Company access/membership denied or registrant no longer a member", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/BasicSetupAccessDenied" }, { "$ref": "#/components/schemas/BasicSetupProblem" } ] } } } }, "409": { "description": "Email unverified or domain conflict: basic_setup_already_completed, basic_setup_registration_required, company_not_provisionable", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/BasicSetupUnverifiedEmail" }, { "$ref": "#/components/schemas/BasicSetupMessage" }, { "$ref": "#/components/schemas/BasicSetupProblem" } ] } } } }, "422": { "description": "Laravel validation failure; invalid RIF/cédula in errors.document_number", "content": { "application/json": { "schema": { "required": [ "message", "errors" ], "properties": { "message": { "type": "string" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" } } } }, "500": { "description": "Unexpected persistence failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicSetupProblem" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/first-companies": { "post": { "tags": [ "Backoffice - First Companies" ], "summary": "Register the first company with an admin user", "operationId": "cae56ca5683d6f1761c108446967cf14", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "companyId", "companyName", "name", "email", "password", "password_confirmation", "phone", "turnstileToken" ], "properties": { "phone": { "description": "Whitespace is trimmed and collapsed before validation; optional leading +, internal spaces, at least six ASCII digits and at most 30 total characters.", "type": "string", "pattern": "^(?=(?:[^0-9]*[0-9]){6})[+]?[0-9 ]+$", "maxLength": 30, "minLength": 6 }, "contractedSeats": { "type": "integer", "default": 1, "maximum": 50, "minimum": 1 }, "turnstileToken": { "type": "string", "maxLength": 2048, "minLength": 1 }, "utm_source": { "type": "string", "maxLength": 255 }, "utm_medium": { "type": "string", "maxLength": 255 }, "utm_campaign": { "type": "string", "maxLength": 255 }, "utm_content": { "type": "string", "maxLength": 255 }, "fbclid": { "type": "string", "maxLength": 2048 }, "companyId": { "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426655440000", "maxLength": 36 }, "companyName": { "type": "string", "example": "Company name", "maxLength": 255 }, "name": { "type": "string", "example": "user name", "maxLength": 255 }, "email": { "description": "Lowercase only: a value that changes when lowercased is rejected. Must not belong to an existing account. Either failure is a 422 under `errors.email`.", "type": "string", "format": "email", "example": "admin@example.com", "maxLength": 255 }, "password": { "description": "At least 8 characters, with no further complexity rule. Must be repeated in `password_confirmation`; a mismatch is a 422 under `errors.password`.", "type": "string", "example": "password", "minLength": 8 }, "password_confirmation": { "description": "Repeats `password`. It has no rule of its own: when it is missing or differs, the 422 names `errors.password`.", "type": "string", "example": "password" } }, "type": "object" } } } }, "responses": { "200": { "description": "Company and admin user registered successfully. The body is an empty object.", "content": { "application/json": { "schema": { "type": "object" } } } }, "422": { "description": "Validation error, including an email that already belongs to an account", "content": { "application/json": { "schema": { "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string", "example": "The given data was invalid." }, "error_code": { "type": "string", "example": null, "nullable": true }, "errors": { "type": "object", "example": { "email": [ "The email has already been taken." ] }, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" } } } }, "409": { "description": "`companyId` belongs to an existing company (`company_already_exists`); nothing is registered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyProblem" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "headers": { "X-RateLimit-Limit": { "description": "The rate limit ceiling for that given request", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "The number of requests left for the time window", "schema": { "type": "integer" } }, "Retry-After": { "description": "The number of seconds to wait before making another request", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Too Many Requests" }, "detail": { "type": "string", "example": "Rate limit exceeded. Please try again later." }, "status": { "type": "integer", "example": 429 } }, "type": "object" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Internal Server Error" }, "status": { "type": "integer", "example": 500 }, "detail": { "type": "string", "example": "An Unexpected Error Occurred" } }, "type": "object" } } } } } } }, "/api/backoffice/{tenant}/companies/{id}/tax-attributes": { "get": { "tags": [ "Backoffice - Companies" ], "summary": "List the company's vigencias of tax attributes", "description": "Returns every vigencia, newest effective date first. The list is not paginated: a company records one row per change of tax standing. The server does not mark which vigencia is the current one — that depends on today in the company's timezone, so the caller picks the greatest effective_from on or before its own today and labels later rows as upcoming. A company with the fiscal capability and no vigencias returns an empty list, never a 404. Each vigencia carries its non-blocking `warnings` (MER-5392): VAT_WITHHOLDING_AGENT_NOT_SPECIAL_TAXPAYER when it marks a VAT withholding agent that is no special taxpayer, since PA SNAT/2025/000054 makes only notified special taxpayers VAT withholding agents; the vigencia is still recorded and still withholds. `{id}` must be the path tenant.", "operationId": "15a81aa91ff1e5d8cd663451a3695682", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "The company whose vigencias are listed. Must equal {tenant}; any other value returns 404.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The vigencias, ordered by effective_from descending", "content": { "application/json": { "schema": { "properties": { "items": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid", "example": "0199c0b2-7a41-7c3d-9e02-4f5a6b7c8d90" }, "effective_from": { "type": "string", "format": "date", "example": "2026-10-01" }, "vat_taxpayer_type": { "type": "string", "example": "ordinary", "enum": [ "ordinary", "formal", "non_taxpayer" ] }, "special_taxpayer": { "type": "boolean", "example": true }, "vat_withholding_agent": { "type": "boolean", "example": true }, "islr_withholding_agent": { "type": "boolean", "example": false }, "igtf_perception_agent": { "type": "boolean", "example": true }, "warnings": { "description": "Non-blocking notices about how the vigencia's attributes combine; always present, empty when there is nothing to warn about (MER-5392).", "type": "array", "items": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "example": "VAT_WITHHOLDING_AGENT_NOT_SPECIAL_TAXPAYER", "enum": [ "VAT_WITHHOLDING_AGENT_NOT_SPECIAL_TAXPAYER" ] }, "message": { "description": "Spanish text for the operator.", "type": "string" } }, "type": "object" } } }, "type": "object" } } }, "type": "object" } } } }, "403": { "description": "Missing backoffice.accounting.settings.fiscal-settings.view", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Forbidden" }, "status": { "type": "integer", "example": 403 }, "detail": { "type": "string", "example": "You do not have permission to access this resource." } }, "type": "object" } } } }, "404": { "description": "company_not_found: {id} is not the path tenant", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "error_code": { "type": "string", "example": "company_not_found" } }, "type": "object" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Internal Server Error" }, "status": { "type": "integer", "example": 500 }, "detail": { "type": "string", "example": "An Unexpected Error Occurred" } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Companies" ], "summary": "Record a new vigencia of the company's tax attributes", "description": "Appends one immutable snapshot of the company's tax standing, effective from a business date. Vigencias are never edited or deleted: a change, a lost attribute or a correction is a new vigencia, so there is no PUT and no DELETE. The first vigencia may carry any past date; every later one must be strictly after the latest; future dates are allowed. Resending the same `id` with an identical payload returns 201 and creates nothing. The response body is empty: read GET for the canonical values. `{id}` must be the path tenant. An API key needs the `write` ability.", "operationId": "e591c3cbc7f7fee9893dcf8b83a6e7ef", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "The company recording the vigencia. Must equal {tenant}; any other value returns 404 once the body is well-formed.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "id", "effective_from", "vat_taxpayer_type", "special_taxpayer", "vat_withholding_agent", "islr_withholding_agent", "igtf_perception_agent" ], "properties": { "id": { "description": "Client-generated identifier of the vigencia. Generate it once when the dialog opens so a double submit is one vigencia.", "type": "string", "format": "uuid", "example": "0199c0b2-7a41-7c3d-9e02-4f5a6b7c8d90" }, "effective_from": { "description": "Business date the vigencia starts applying on, as Y-m-d.", "type": "string", "format": "date", "example": "2026-10-01" }, "vat_taxpayer_type": { "type": "string", "example": "ordinary", "enum": [ "ordinary", "formal", "non_taxpayer" ] }, "special_taxpayer": { "description": "Sujeto pasivo especial.", "type": "boolean", "example": true }, "vat_withholding_agent": { "description": "Agente de retención de IVA.", "type": "boolean", "example": true }, "islr_withholding_agent": { "description": "Agente de retención de ISLR.", "type": "boolean", "example": false }, "igtf_perception_agent": { "description": "Agente de percepción de IGTF.", "type": "boolean", "example": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Vigencia recorded, or an identical replay of one already recorded" }, "403": { "description": "Missing backoffice.accounting.settings.fiscal-settings.update, or a read-only API key (api_key_write_ability_required)", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Forbidden" }, "status": { "type": "integer", "example": 403 }, "detail": { "type": "string", "example": "You do not have permission to access this resource." } }, "type": "object" } } } }, "404": { "description": "company_not_found: {id} is not the path tenant, or the company does not exist", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "error_code": { "type": "string", "example": "company_not_found" } }, "type": "object" } } } }, "409": { "description": "The effective date is already taken by another vigencia, or the id is already used by a different one", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "detail": { "type": "string", "example": "La empresa <0199a1f4-1111-7c3d-9e02-4f5a6b7c8d90> ya tiene una vigencia desde <2026-10-01>" }, "error_code": { "type": "string", "enum": [ "tax_attributes_date_taken", "tax_attributes_id_conflict" ] } }, "type": "object" } } } }, "422": { "description": "Either an `errors` map keyed by field with a null `error_code` (shape validation), or a domain `error_code` with a null `errors`", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string", "example": "La fecha de vigencia <2026-09-15> debe ser posterior a la última vigencia <2026-10-01> de la empresa <0199a1f4-1111-7c3d-9e02-4f5a6b7c8d90>" }, "error_code": { "type": "string", "nullable": true, "enum": [ "invalid_effective_from", "invalid_vat_taxpayer_type", "fiscal_profile_not_enabled", "fiscal_profile_required", "tax_attributes_out_of_order" ] }, "errors": { "type": "object", "nullable": true } }, "type": "object" } } } }, "429": { "description": "Too many attempts: 10 per minute per user" }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Internal Server Error" }, "status": { "type": "integer", "example": 500 }, "detail": { "type": "string", "example": "An Unexpected Error Occurred" } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/fiscal/fiscal-periods/{period}/close": { "post": { "tags": [ "Backoffice - Fiscal - Fiscal Periods" ], "summary": "Close a fiscal period", "description": "Closes a Fiscal Period in review (ADR 0264): its current Declared Set stays what the company declared, and the next period may freeze. Audited as `backoffice.fiscal.fiscal-periods.closed`. Requires `backoffice.fiscal.fiscal-periods.manage`.", "operationId": "closeFiscalPeriod", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "period", "in": "path", "description": "The period to close: a month YYYY-MM or a fortnight YYYY-MM-1 or YYYY-MM-2", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])(-[12])?$", "example": "2026-09" } } ], "responses": { "200": { "description": "The period is closed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FiscalPeriod" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks the manage permission" }, "404": { "description": "The company does not exist (company_not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FiscalPeriodProblem" }, "example": { "title": "Not Found", "status": 404, "detail": "La empresa con el id … no existe", "error_code": "company_not_found", "errors": null } } } }, "409": { "description": "The period is not in review, with `period_status` (fiscal_period_status_conflict), or a concurrent request changed the company's periods first (fiscal_period_concurrent_write)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FiscalPeriodProblem" }, "example": { "title": "Conflict", "status": 409, "detail": "El período fiscal <2026-09> está en estado , que no permite esta transición", "error_code": "fiscal_period_status_conflict", "errors": null, "period_status": "open" } } } }, "422": { "description": "The period is malformed (errors.period), or the company declares the month by the other type, with `expected_period_type` (fiscal_period_type_mismatch)", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/FiscalPeriodValidationProblem" }, { "$ref": "#/components/schemas/FiscalPeriodProblem" } ] }, "example": { "title": "Unprocessable Entity", "status": 422, "detail": "The given data was invalid.", "error_code": null, "errors": { "period": [ "The period must be a month YYYY-MM or a fortnight YYYY-MM-1 or YYYY-MM-2, for example 2026-09 or 2026-09-2." ] } } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/fiscal/fiscal-periods/{period}/declared-documents": { "get": { "tags": [ "Backoffice - Fiscal - Fiscal Periods" ], "summary": "List the documents a fiscal period declared", "description": "Pages the documents of a Fiscal Period's Declared Set in the order the VAT books print them: by Book Date, document number and id. The current version is read unless `version` names an earlier one, which still answers once superseded. Requires `backoffice.fiscal.fiscal-periods.view`.", "operationId": "searchFiscalPeriodDeclaredDocuments", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "period", "in": "path", "description": "A month YYYY-MM or a fortnight YYYY-MM-1 or YYYY-MM-2", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])(-[12])?$", "example": "2026-09" } }, { "name": "version", "in": "query", "description": "The Declared Set version; the current one when absent.", "required": false, "schema": { "type": "integer", "example": 1, "minimum": 1 } }, { "name": "book", "in": "query", "description": "Only the documents of one book.", "required": false, "schema": { "type": "string", "enum": [ "sales", "purchases" ] } }, { "name": "type", "in": "query", "description": "Only documents of one type, or of several when repeated / passed as an array (MER-4147).", "required": false, "schema": { "oneOf": [ { "type": "string", "enum": [ "invoice", "credit_note", "debit_note", "received_vat_withholding", "practiced_vat_withholding" ] }, { "type": "array", "items": { "type": "string", "enum": [ "invoice", "credit_note", "debit_note", "received_vat_withholding", "practiced_vat_withholding" ] } } ] } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "One page of the declared documents", "content": { "application/json": { "schema": { "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DeclaredDocument" } }, "meta": { "$ref": "#/components/schemas/DeclaredDocumentsMeta" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks the view permission" }, "404": { "description": "The period was never frozen, or it has no set of the version asked for (declared_set_not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FiscalPeriodProblem" }, "example": { "title": "Not Found", "status": 404, "detail": "El período fiscal <2026-09> nunca se congeló, así que no tiene conjunto declarado", "error_code": "declared_set_not_found", "errors": null } } } }, "422": { "description": "The period is malformed (errors.period) or a query parameter is, named in `errors`: `version`, `book`, `type`, `page` or `per_page`", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/FiscalPeriodValidationProblem" }, { "$ref": "#/components/schemas/FiscalPeriodProblem" } ] }, "example": { "title": "Unprocessable Entity", "status": 422, "detail": "The given data was invalid.", "error_code": null, "errors": { "per_page": [ "The per page field must not be greater than 100." ] } } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/fiscal/fiscal-periods/{period}/freeze": { "post": { "tags": [ "Backoffice - Fiscal - Fiscal Periods" ], "summary": "Freeze a fiscal period", "description": "Moves an ended Fiscal Period from `open` to `in_review` and writes the next version of its Declared Set (ADR 0264): every document dated since declarations started that no frozen period declared, in signed bolívares, with those dated before the period marked late: the approved sales invoices, credit notes and debit notes by their emission date; the approved purchase invoices, supplier credit notes and debit notes by their registration date; the VAT withholdings the company practiced, by their trigger date; and each supported VAT withholding its clients practiced, one row per invoice line, by the day its certificate arrived, an adjustment as its own negative rows (ADR 0263). Opening documents, drafts, ISLR withholdings and exclusions at 0 % are never declared; a cancelled sale that carries its number is declared as cancelled with zero amounts. A month is a fortnight period for a special taxpayer on its first day (ADR 0265). The period must have ended in the company's timezone, no other period may be in review, and after the first freeze it must be the period right after the latest closed one, or, while none is closed, the declarations start: a reopened period that was the only one closed freezes again before any other. A sale without its number, a document without its bolívares or a practiced VAT withholding without its certificate refuses the freeze with `missing` and writes nothing. Audited as `backoffice.fiscal.fiscal-periods.frozen`. Requires `backoffice.fiscal.fiscal-periods.manage`.", "operationId": "freezeFiscalPeriod", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "period", "in": "path", "description": "The period to freeze: a month YYYY-MM or a fortnight YYYY-MM-1 or YYYY-MM-2", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])(-[12])?$", "example": "2026-09" } } ], "responses": { "200": { "description": "The period is in review with its new version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FiscalPeriod" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks the manage permission" }, "404": { "description": "The company does not exist (company_not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FiscalPeriodProblem" }, "example": { "title": "Not Found", "status": 404, "detail": "La empresa con el id … no existe", "error_code": "company_not_found", "errors": null } } } }, "409": { "description": "The period is not open, with `period_status` (fiscal_period_status_conflict); another period is in review, with `period_in_review` (fiscal_period_review_in_progress); or a concurrent request changed the company's periods first (fiscal_period_concurrent_write)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FiscalPeriodProblem" }, "example": { "title": "Conflict", "status": 409, "detail": "El período fiscal <2026-10> no se puede congelar mientras <2026-09> esté en revisión; cierra <2026-09> o vuélvelo a abierto primero", "error_code": "fiscal_period_review_in_progress", "errors": null, "period_in_review": "2026-09" } } } }, "422": { "description": "The period is malformed (errors.period); the company declares the month by the other type, with `expected_period_type` (fiscal_period_type_mismatch); the period has not ended (fiscal_period_not_ended); it is not the period expected next (right after the latest closed one, or, while none is closed, the declarations start), with `expected_period` (fiscal_period_out_of_order); or documents have essential gaps, listed in `missing` (fiscal_period_not_ready)", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/FiscalPeriodValidationProblem" }, { "$ref": "#/components/schemas/FiscalPeriodProblem" } ] }, "example": { "title": "Unprocessable Entity", "status": 422, "detail": "El período fiscal <2026-09> no se puede congelar: <1> documentos tienen faltantes esenciales; consulta missing", "error_code": "fiscal_period_not_ready", "errors": null, "missing": [ { "code": "DOCUMENT_NUMBER_MISSING", "book": "sales", "document_type": "invoice", "document_id": "0199a000-0000-7000-8000-000000000001", "document_code": "INV00012", "affected_document_id": null, "book_date": "2026-09-03" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/fiscal/fiscal-periods/{period}": { "get": { "tags": [ "Backoffice - Fiscal - Fiscal Periods" ], "summary": "Show a fiscal period with its declared set versions", "description": "One Fiscal Period with every version of its Declared Set, oldest first (ADR 0264): who froze each one and when, and, once an unfreeze or a reopen superseded it, who did it, when and why. A period that never froze is `open` with `version` null and no versions. Each version's documents stay readable through `declared-documents?version=N`. Writes nothing. Requires `backoffice.fiscal.fiscal-periods.view`.", "operationId": "showFiscalPeriod", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "period", "in": "path", "description": "A month YYYY-MM or a fortnight YYYY-MM-1 or YYYY-MM-2", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])(-[12])?$", "example": "2026-09" } } ], "responses": { "200": { "description": "The period with its versions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FiscalPeriodDetail" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks the view permission" }, "404": { "description": "The company does not exist (company_not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FiscalPeriodProblem" }, "example": { "title": "Not Found", "status": 404, "detail": "La empresa con el id … no existe", "error_code": "company_not_found", "errors": null } } } }, "422": { "description": "The period is malformed (errors.period), or the company declares the month by the other type, with `expected_period_type` (fiscal_period_type_mismatch)", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/FiscalPeriodValidationProblem" }, { "$ref": "#/components/schemas/FiscalPeriodProblem" } ] }, "example": { "title": "Unprocessable Entity", "status": 422, "detail": "La empresa declara el mes de <2026-09> por períodos de tipo fortnight, así que <2026-09> no es uno de sus períodos fiscales", "error_code": "fiscal_period_type_mismatch", "errors": null, "expected_period_type": "fortnight" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/fiscal/fiscal-periods/{period}/readiness": { "get": { "tags": [ "Backoffice - Fiscal - Fiscal Periods" ], "summary": "Check whether a fiscal period is ready to freeze", "description": "What the Fiscal Period that freezes next would declare if it froze now, from `declarations_from` through its last day: the essential gaps that keep it from freezing, in `missing`, and the warnings that do not, such as drafts dated in its own days. Writes nothing. It refuses what the freeze refuses except a period that has not ended, so the period in progress can be previewed: a period in review or closed has a fixed set, no period has readiness while another is in review, and a period out of order names the one that freezes next. Requires `backoffice.fiscal.fiscal-periods.view`.", "operationId": "showFiscalPeriodReadiness", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "period", "in": "path", "description": "A month YYYY-MM or a fortnight YYYY-MM-1 or YYYY-MM-2", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])(-[12])?$", "example": "2026-10" } } ], "responses": { "200": { "description": "The period's readiness", "content": { "application/json": { "schema": { "required": [ "period", "period_type", "starts_on", "ends_on", "declarations_from", "ready", "missing", "warnings" ], "properties": { "period": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])(-[12])?$", "example": "2026-10" }, "period_type": { "type": "string", "example": "month", "enum": [ "month", "fortnight" ] }, "starts_on": { "type": "string", "format": "date", "example": "2026-10-01" }, "ends_on": { "type": "string", "format": "date", "example": "2026-10-31" }, "declarations_from": { "description": "The first Book Date the freeze would read: where declarations started, or the period's first day.", "type": "string", "format": "date", "example": "2026-09-01" }, "ready": { "description": "True when nothing is missing.", "type": "boolean", "example": false }, "missing": { "type": "array", "items": { "$ref": "#/components/schemas/FiscalPeriodGap" } }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/FiscalPeriodWarning" } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks the view permission" }, "404": { "description": "The company does not exist (company_not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FiscalPeriodProblem" }, "example": { "title": "Not Found", "status": 404, "detail": "La empresa con el id … no existe", "error_code": "company_not_found", "errors": null } } } }, "409": { "description": "The period is in review or closed, with `period_status` (fiscal_period_status_conflict), or another period is in review, with `period_in_review` (fiscal_period_review_in_progress)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FiscalPeriodProblem" }, "example": { "title": "Conflict", "status": 409, "detail": "El período fiscal <2026-09> está en estado , que no permite esta transición", "error_code": "fiscal_period_status_conflict", "errors": null, "period_status": "in_review" } } } }, "422": { "description": "The period is malformed (errors.period); the company declares the month by the other type, with `expected_period_type` (fiscal_period_type_mismatch); or it is not the period expected next (right after the latest closed one, or, while none is closed, the declarations start), with `expected_period` (fiscal_period_out_of_order)", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/FiscalPeriodValidationProblem" }, { "$ref": "#/components/schemas/FiscalPeriodProblem" } ] }, "example": { "title": "Unprocessable Entity", "status": 422, "detail": "La empresa declara el mes de <2026-09> por períodos de tipo fortnight, así que <2026-09> no es uno de sus períodos fiscales", "error_code": "fiscal_period_type_mismatch", "errors": null, "expected_period_type": "fortnight" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/fiscal/fiscal-periods/{period}/reopen": { "post": { "tags": [ "Backoffice - Fiscal - Fiscal Periods" ], "summary": "Reopen a fiscal period", "description": "Returns the latest closed Fiscal Period to `open` to correct what it filed (ADR 0264, ADR 0265). Its current Declared Set is superseded with who, when and the reason, never deleted: every version stays readable through `GET …/fiscal-periods/{period}` (`versions`) and `declared-documents?version=N`, and the next freeze writes the next version with the documents' current values. Only the latest closed period reopens, so a correction to an older one reopens every later one first, and not while a later period is in review, which must be unfrozen first. A reopened period keeps marking where declarations start and, while no period is closed, it must freeze before any other. Who reopened it, when and why stay on the period after it closes again. Audited as `backoffice.fiscal.fiscal-periods.reopened` with the superseded version and the reason. Requires `backoffice.fiscal.fiscal-periods.reopen`, which no role holds by default; `backoffice.fiscal.fiscal-periods.manage` alone is not enough.", "operationId": "reopenFiscalPeriod", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "period", "in": "path", "description": "The period to reopen: a month YYYY-MM or a fortnight YYYY-MM-1 or YYYY-MM-2", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])(-[12])?$", "example": "2026-09" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "reason" ], "properties": { "reason": { "description": "Why the filed period reopens: 1 to 500 characters once trimmed at both ends; inner line breaks are kept.", "type": "string", "example": "Corrección de número de control de FV03", "maxLength": 500, "minLength": 1 } }, "type": "object" } } } }, "responses": { "200": { "description": "The period is open again", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FiscalPeriod" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks the reopen permission; manage alone is not enough" }, "404": { "description": "The company does not exist (company_not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FiscalPeriodProblem" }, "example": { "title": "Not Found", "status": 404, "detail": "La empresa con el id … no existe", "error_code": "company_not_found", "errors": null } } } }, "409": { "description": "The period is not closed, with `period_status` (fiscal_period_status_conflict); a later period is in review and must be unfrozen first, with `period_in_review` (fiscal_period_review_in_progress); or a concurrent request changed the company's periods first (fiscal_period_concurrent_write)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FiscalPeriodProblem" }, "example": { "title": "Conflict", "status": 409, "detail": "El período fiscal <2026-09> está en estado , que no permite esta transición", "error_code": "fiscal_period_status_conflict", "errors": null, "period_status": "open" } } } }, "422": { "description": "The period is malformed (errors.period); the reason is missing, blank or longer than 500 characters once trimmed (errors.reason); the company declares the month by the other type, with `expected_period_type` (fiscal_period_type_mismatch); or the period is not the latest closed one, with `expected_period` naming the period to reopen first (fiscal_period_out_of_order)", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/FiscalPeriodValidationProblem" }, { "$ref": "#/components/schemas/FiscalPeriodProblem" } ] }, "example": { "title": "Unprocessable Entity", "status": 422, "detail": "El período fiscal <2026-08> no se puede reabrir mientras <2026-09> esté cerrado después de él; reabre <2026-09> primero", "error_code": "fiscal_period_out_of_order", "errors": null, "expected_period": "2026-09" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/fiscal/fiscal-periods/{period}/unfreeze": { "post": { "tags": [ "Backoffice - Fiscal - Fiscal Periods" ], "summary": "Unfreeze a fiscal period", "description": "Returns a Fiscal Period in review to `open` (ADR 0264). Its current Declared Set is superseded with who, when and the reason, never deleted, and its documents are free for the next freeze, which writes the next version. Audited as `backoffice.fiscal.fiscal-periods.unfrozen` with the reason. Requires `backoffice.fiscal.fiscal-periods.manage`.", "operationId": "unfreezeFiscalPeriod", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "period", "in": "path", "description": "The period to unfreeze: a month YYYY-MM or a fortnight YYYY-MM-1 or YYYY-MM-2", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])(-[12])?$", "example": "2026-09" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "reason" ], "properties": { "reason": { "description": "Why the period returns to open: 1 to 500 characters once trimmed at both ends.", "type": "string", "example": "Factura omitida en la quincena" } }, "type": "object" } } } }, "responses": { "200": { "description": "The period is open again", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FiscalPeriod" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks the manage permission" }, "404": { "description": "The company does not exist (company_not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FiscalPeriodProblem" }, "example": { "title": "Not Found", "status": 404, "detail": "La empresa con el id … no existe", "error_code": "company_not_found", "errors": null } } } }, "409": { "description": "The period is not in review, with `period_status` (fiscal_period_status_conflict), or a concurrent request changed the company's periods first (fiscal_period_concurrent_write)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FiscalPeriodProblem" }, "example": { "title": "Conflict", "status": 409, "detail": "El período fiscal <2026-09> está en estado , que no permite esta transición", "error_code": "fiscal_period_status_conflict", "errors": null, "period_status": "open" } } } }, "422": { "description": "The period is malformed (errors.period); the reason is missing, blank or longer than 500 characters once trimmed (errors.reason); or the company declares the month by the other type, with `expected_period_type` (fiscal_period_type_mismatch)", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/FiscalPeriodValidationProblem" }, { "$ref": "#/components/schemas/FiscalPeriodProblem" } ] }, "example": { "title": "Unprocessable Entity", "status": 422, "detail": "The given data was invalid.", "error_code": null, "errors": { "reason": [ "The reason must hold 1 to 500 characters of text once trimmed." ] } } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/fiscal/fiscal-periods": { "get": { "tags": [ "Backoffice - Fiscal - Fiscal Periods" ], "summary": "List the fiscal periods", "description": "Lists the Fiscal Periods of the company's current month, in its timezone, and of the eleven months before it, plus every period that was ever frozen and the period that may freeze next, newest first; a fortnight month lists its second fortnight before its first (ADR 0265). Each item says whether it may freeze now by the same order rules the freeze applies. `declarations_start` is the earliest period frozen, closed or reopened, where Backoffice declarations start; null before the first freeze or once the only frozen period is unfrozen; a closed period that reopens keeps marking it. Requires `backoffice.fiscal.fiscal-periods.view`.", "operationId": "searchFiscalPeriods", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The company's fiscal periods", "content": { "application/json": { "schema": { "required": [ "declarations_start", "periods" ], "properties": { "declarations_start": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])(-[12])?$", "example": "2026-09", "nullable": true }, "periods": { "description": "Newest first.", "type": "array", "items": { "$ref": "#/components/schemas/FiscalPeriodListItem" } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks the view permission" }, "404": { "description": "The company does not exist (company_not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FiscalPeriodProblem" }, "example": { "title": "Not Found", "status": 404, "detail": "La empresa con el id … no existe", "error_code": "company_not_found", "errors": null } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/fiscal/igtf-applicability": { "get": { "tags": [ "Backoffice - Fiscal Rules" ], "summary": "Preview the IGTF of a collection or payment line paid through an instrument on a date", "description": "What the collection and payment forms show for one of the tenant's payment instruments on the day of the cash event (MER-2718): `collection` is the perceived IGTF a collection line would carry, classified by the same rules the collection itself applies; `paid_suggestion` is the IGTF Paid rate a provider may charge on a payment line, only when `provider_id` names a provider that is a special taxpayer on `date`, a reading an accountant should confirm (ADR 0367). Informational: nothing is written and the instrument need not be active. Readable by whoever can register a collection line or a payment line that carries IGTF: `collections.create`, `backoffice.sales.collections.advance`, `backoffice.purchases.payments.create` OR `backoffice.purchases.payments.advance` (a registered multi-permission carve-out; a collection refund never perceives IGTF, so `backoffice.sales.collections.refund` alone does not read it); any of them is checked before the instrument is looked up, so a 403 never tells whether it exists. An instrument of another company answers 404 exactly like an unknown one.", "operationId": "8dcb3452a46249a831f0e65657c7c5f7", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "instrument_id", "in": "query", "description": "The tenant's payment instrument. Required.", "required": true, "schema": { "type": "string", "format": "uuid", "example": "0199e0a0-0000-7000-8000-0000000000b1" } }, { "name": "date", "in": "query", "description": "Day of the cash event, exactly Y-m-d. Required.", "required": true, "schema": { "type": "string", "format": "date", "example": "2026-09-11" } }, { "name": "provider_id", "in": "query", "description": "The provider the payment goes to. Optional: collection forms have none. Read only for a holder of `backoffice.purchases.payments.create`, `backoffice.purchases.payments.advance` or `backoffice.purchases.payments.update`; the last does not open this endpoint by itself. An unknown provider or another company's reads as not a special taxpayer.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "0199e0a0-0000-7000-8000-0000000000d1" } } ], "responses": { "200": { "description": "The IGTF of a collection line and the IGTF Paid suggestion of a payment line", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FiscalIgtfApplicabilityPreview" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "403": { "description": "None of collections.create, backoffice.sales.collections.advance, backoffice.purchases.payments.create or backoffice.purchases.payments.advance", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Forbidden" }, "status": { "type": "integer", "example": 403 }, "detail": { "type": "string", "example": "You do not have permission to access this resource." } }, "type": "object" } } } }, "404": { "description": "payment_instrument_not_found: the tenant has no such instrument (unknown, or another company's); company_not_found: the tenant company does not exist", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "detail": { "type": "string", "example": "El instrumento de pago <0199e0a0-0000-7000-8000-0000000000b1> no existe" }, "error_code": { "type": "string", "example": "payment_instrument_not_found" } }, "type": "object" } } } }, "422": { "description": "`instrument_id` is missing or not a UUID, `date` is missing or is not an existing Y-m-d day, or `provider_id` is present and not a UUID", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string", "example": "The given data was invalid." }, "errors": { "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Internal Server Error" }, "status": { "type": "integer", "example": 500 }, "detail": { "type": "string", "example": "An Unexpected Error Occurred" } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/fiscal/islr-concepts/lookup": { "get": { "tags": [ "Backoffice - Fiscal - ISLR Concept Lookups" ], "summary": "Lookup the ISLR concepts a payee type can be classified under, for tenant forms", "description": "Tenant membership is enough; no module permission is required, so the purchases-invoice line editor and the Item form can offer the ISLR classification to any member (MER-3704). Lists the same concepts as GET /fiscal/islr-concepts, which requires backoffice.fiscal.rules.view: the concepts in force on `date` for `person_type` that are `enabled` and active, in code order. Concepts that are `out_of_scope` or `unresolved` are never listed, so a non-resident or non-domiciled payee answers an empty list, and so does a date before the catalog starts; a suspended concept is left out from its suspension date on. Each concept is projected to its code and label only: rates, the tax unit and the rule's provenance stay behind the management endpoint. «No sujeta a retención de ISLR» (`not_subject`) is a classification, not a concept, and is never listed. The catalogs are global: the tenant only decides which country's rules are read.", "operationId": "78b47bdf15f64f25c89abe240e598607", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "date", "in": "query", "description": "Day the concepts must be in force on, exactly Y-m-d: the purchases invoice's registration date, or today for an Item's default. Required.", "required": true, "schema": { "type": "string", "format": "date", "example": "2026-09-17" } }, { "name": "person_type", "in": "query", "description": "ISLR Person Type of the payee. Required; the canonical value only.", "required": true, "schema": { "type": "string", "example": "natural_resident", "enum": [ "natural_resident", "natural_non_resident", "legal_domiciled", "legal_non_domiciled" ] } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 200, "minimum": 1 } } ], "responses": { "200": { "description": "One page of the enabled concepts in force on `date` for `person_type`, in code order; an empty page when there are none", "content": { "application/json": { "schema": { "required": [ "items", "total", "per_page", "current_page" ], "properties": { "items": { "type": "array", "items": { "required": [ "code", "label" ], "properties": { "code": { "description": "Stable Decree 1.808 art. 9 concept code: the value an Item's default_islr_classification or a purchases-invoice line's islr_classification stores.", "type": "string", "pattern": "^[a-z][a-z0-9_]{0,63}$", "example": "professional_fees" }, "label": { "description": "Spanish label for the concept selector.", "type": "string", "example": "Honorarios profesionales no mercantiles", "maxLength": 120 } }, "type": "object", "additionalProperties": false } }, "total": { "type": "integer", "example": 7, "minimum": 0 }, "per_page": { "type": "integer", "example": 20, "maximum": 200, "minimum": 1 }, "current_page": { "type": "integer", "example": 1, "minimum": 1 } }, "type": "object", "additionalProperties": false } } } }, "401": { "description": "Unauthenticated (Laravel Sanctum)", "content": { "application/json": { "schema": { "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "403": { "description": "Forbidden, always answered by middleware: tenant membership adds a reason; company access and API-key guardrails send only title, status and detail", "content": { "application/json": { "schema": { "required": [ "title", "status", "detail" ], "properties": { "title": { "type": "string", "example": "Forbidden" }, "status": { "type": "integer", "example": 403 }, "detail": { "type": "string", "example": "You do not have access to this tenant" }, "reason": { "type": "string", "example": "DENIED_NO_MEMBERSHIP" } }, "type": "object" } } } }, "404": { "description": "Unknown tenant or API key bound to another company (middleware message), or company not found (controller Problem)", "content": { "application/json": { "schema": { "oneOf": [ { "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Recurso no encontrado" } }, "type": "object" }, { "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "detail": { "type": "string" }, "error_code": { "type": "string", "example": "company_not_found", "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true } }, "type": "object" } ] } } } }, "422": { "description": "`date` is missing or is not an existing Y-m-d day, `person_type` is missing or not one of the four canonical values, `page` is below 1, or `per_page` is outside 1..200", "content": { "application/json": { "schema": { "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string", "example": "The given data was invalid." }, "error_code": { "type": "string", "example": null, "nullable": true }, "errors": { "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Internal Server Error" }, "status": { "type": "integer", "example": 500 }, "detail": { "type": "string", "example": "An Unexpected Error Occurred" } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/fiscal/islr-concepts": { "get": { "tags": [ "Backoffice - Fiscal Rules" ], "summary": "List the ISLR concepts a payee type can be withheld under on a date", "description": "A search over the global ISLR concepts catalog (Decree 1.808 art. 9): the concepts in force on `date` for `person_type` that are `enabled` and active, in code order, each with its rate, base, minimum base in tax units, subtractor factor and subtractor in bolívares. Concepts that are `out_of_scope` or `unresolved` are never listed, so a non-resident or non-domiciled payee answers an empty list. A suspended concept is left out from its suspension date on. `tax_unit` is the unit in force on `date`, or null before the first one or while it is suspended; then every `subtractor_bs` is null too. The catalogs are global: the tenant only decides which country's rules are read. Not paginated: at most 31 concepts per payee type.", "operationId": "8777c3ac14ada5eb3e444a5e5b5886eb", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "date", "in": "query", "description": "Day of the payment, exactly Y-m-d. Required.", "required": true, "schema": { "type": "string", "format": "date", "example": "2026-09-17" } }, { "name": "person_type", "in": "query", "description": "ISLR Person Type of the payee. Required; the canonical value only.", "required": true, "schema": { "type": "string", "example": "natural_resident", "enum": [ "natural_resident", "natural_non_resident", "legal_domiciled", "legal_non_domiciled" ] } } ], "responses": { "200": { "description": "The enabled concepts in force on `date` for `person_type`, in code order", "content": { "application/json": { "schema": { "required": [ "date", "country", "person_type", "tax_unit", "concepts" ], "properties": { "date": { "type": "string", "format": "date", "example": "2026-09-17" }, "country": { "description": "ISO 3166-1 alpha-2 country of the tenant", "type": "string", "example": "VE" }, "person_type": { "type": "string", "example": "natural_resident", "enum": [ "natural_resident", "natural_non_resident", "legal_domiciled", "legal_non_domiciled" ] }, "tax_unit": { "description": "The tax unit in force on `date`; null before the first unit or while it is suspended.", "required": [ "rule_id", "value_bs", "effective_from", "source_article", "matrix_rule_id", "matrix_version" ], "properties": { "rule_id": { "type": "string", "format": "uuid", "example": "45192523-531e-533e-850b-8c083ad59409" }, "value_bs": { "description": "Value of one tax unit in bolívares (VES).", "type": "string", "pattern": "^\\d{1,10}\\.\\d{2}$", "example": "43.00" }, "effective_from": { "type": "string", "format": "date", "example": "2025-06-02" }, "source_article": { "type": "string", "example": "PA SNAT/2025/000048, GO 43.140", "maxLength": 120 }, "matrix_rule_id": { "type": "string", "pattern": "^[A-Z]+-\\d{2}$", "example": "ISLR-03" }, "matrix_version": { "type": "string", "example": "2026-09-20-research-3" } }, "type": "object", "nullable": true, "additionalProperties": false }, "concepts": { "type": "array", "items": { "$ref": "#/components/schemas/FiscalIslrConcept" } } }, "type": "object", "additionalProperties": false } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "403": { "description": "Missing backoffice.fiscal.rules.view", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Forbidden" }, "status": { "type": "integer", "example": 403 }, "detail": { "type": "string", "example": "You do not have permission to access this resource." } }, "type": "object" } } } }, "404": { "description": "company_not_found: the tenant company does not exist", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "error_code": { "type": "string", "example": "company_not_found" } }, "type": "object" } } } }, "422": { "description": "`date` is missing or is not an existing Y-m-d day, or `person_type` is missing or not one of the four canonical values", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string", "example": "The given data was invalid." }, "errors": { "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Internal Server Error" }, "status": { "type": "integer", "example": 500 }, "detail": { "type": "string", "example": "An Unexpected Error Occurred" } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/fiscal/islr-withholdings/{id}/void": { "post": { "tags": [ "Backoffice - Fiscal Withholdings" ], "summary": "Void an ISLR withholding", "description": "Voids an ISLR withholding the company practised and has not remitted (MER-3702, glossary command VoidPracticedWithholding, ADR 0196), with a reason. In the same transaction: the purchases invoice owes the provider again exactly what the withholding relieved in each book (its `withheld_amount` goes down by it and its balance and status follow), its certificate is voided and keeps its number, `islr_withholding.voided` posts dated the company's today inverting every line of its `islr_withholding.determined` entry in both books (one of zero, or one whose legal amount relieved no cent of either book, posted nothing and reverses nothing), and the voiding is written to the audit log as `backoffice.fiscal.islr_withholding.voided.v1` with who voided it and why. A voided withholding answers 409 islr_withholding_already_voided and a remitted one 409 remitted_withholding_requires_adjustment (ADR 0196: it is corrected with an adjustment in a later period); nothing is written. A blank reason, or one longer than 500 characters once trimmed, answers the validator's 422 with `errors.reason` (the domain's invalid_islr_withholding_void_reason guards the same rule and is not expected on the wire). Cancelling the purchases invoice voids its withholding the same way, with the reason «Factura cancelada». Requires `backoffice.fiscal.withholdings.review`; an API key needs the `write` ability.", "operationId": "voidFiscalIslrWithholding", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "The ISLR withholding id.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "reason" ], "properties": { "reason": { "description": "Why it is voided: 1 to 500 characters once trimmed; inner line breaks are kept.", "type": "string", "example": "Concepto mal clasificado; se reclasificará.", "maxLength": 500, "minLength": 1 } }, "type": "object" } } } }, "responses": { "200": { "description": "Withholding voided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FiscalIslrWithholdingVoidResult" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "403": { "description": "Missing backoffice.fiscal.withholdings.review, or a read-only API key (api_key_write_ability_required)", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Forbidden" }, "status": { "type": "integer", "example": 403 }, "detail": { "type": "string", "example": "You do not have permission to access this resource." }, "error_code": { "type": "string", "nullable": true, "enum": [ "api_key_write_ability_required" ] } }, "type": "object" } } } }, "404": { "description": "islr_withholding_not_found: the company keeps no ISLR withholding with this id, another company's included", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "detail": { "type": "string" }, "error_code": { "type": "string", "enum": [ "islr_withholding_not_found", "company_not_found" ] } }, "type": "object" } } } }, "409": { "description": "islr_withholding_already_voided: the withholding is already voided; remitted_withholding_requires_adjustment: it was remitted to SENIAT, so it is corrected with an adjustment in a later period. Nothing is written", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "detail": { "type": "string", "example": "La retención de ISLR ya está anulada." }, "error_code": { "type": "string", "enum": [ "islr_withholding_already_voided", "remitted_withholding_requires_adjustment" ] } }, "type": "object" } } } }, "422": { "description": "A blank or too long reason (`errors.reason`), or an id that is not a UUID (invalid_islr_withholding_id); nothing is written", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string" }, "error_code": { "type": "string", "nullable": true, "enum": [ "invalid_islr_withholding_id", "invalid_islr_withholding_void_reason" ] }, "errors": { "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" } } } }, "500": { "description": "The voiding could not restore the debt or mirror the entry (islr_withholding_posted_transaction_missing, transaction_already_reversed, invalid_transaction_balance, empty_transaction_items, transaction_persistence_failed, purchases_invoice_withholding_restore_failed or purchases_invoice_persistence_failed); nothing is written", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Internal Server Error" }, "status": { "type": "integer", "example": 500 }, "detail": { "type": "string", "example": "An Unexpected Error Occurred" }, "error_code": { "type": "string", "nullable": true } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/fiscal/islr-withholdings": { "get": { "tags": [ "Backoffice - Fiscal Withholdings" ], "summary": "List the ISLR withholdings the company practised", "description": "The ISLR withholdings the company practised as withholding agent (MER-3702, Decree 1.808), each named by its purchases invoice and provider, with the provider's ISLR Person Type frozen at its determination, one row per ISLR Concept it withheld under (the catalog rule it snapshots, its label, the base, the rate, the subtractor rounded once exactly as the certificate prints it, and the amount; `reason` says `below_minimum` when the concept's base did not exceed its minimum and withheld nothing), the amounts, a summary of the certificate that certifies or certified it (whose id opens `GET fiscal/withholding-certificates/{id}`; a voided withholding shows its voided certificate, which keeps its number; one of zero has none), why, when and by whom it was voided, and whether a payment dated before its registration suggests an earlier trigger date (`trigger_date_superseded`, with the suggested day and month; `trigger_date` and `month` never change). `month` is the month of its trigger date, the one it is declared and remitted in. Every filter is optional: `month`, `status`, `provider_id` and `purchases_invoice_id`, which reads the withholdings of one purchases invoice for its record (MER-3705), voided ones included; without `month` every month is read. Rows come newest `trigger_date` first, then newest created, then by id, so pages never repeat nor skip a row. `meta.counts` counts each status under every filter but `status`, naming `determined`, `certified`, `remitted` and `voided` even at zero, and `meta.total` respects every filter. A month without withholdings answers 200 with an empty `data` and zero counts, never a 404; another company's withholdings never appear. Only the query string is read. Paginated by page: `page` from 1, `per_page` 1 to 100 (50 by default). `voidable` is the server's rule for offering «Anular». Statuses are lower case; treat one you do not know as not voidable. Requires `backoffice.fiscal.withholdings.view`.", "operationId": "listFiscalIslrWithholdings", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "month", "in": "query", "description": "The month the withholdings are declared in, the month of their trigger date: `YYYY-MM`.", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$", "example": "2026-09" } }, { "name": "status", "in": "query", "description": "Only the withholdings of this status; `meta.counts` ignores it.", "required": false, "schema": { "type": "string", "enum": [ "determined", "certified", "remitted", "voided" ] } }, { "name": "provider_id", "in": "query", "description": "Only the withholdings practised on this provider.", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "purchases_invoice_id", "in": "query", "description": "Only the withholdings practised on this purchases invoice, in every month unless `month` is sent too.", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "description": "The page, from 1.", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Rows a page.", "required": false, "schema": { "type": "integer", "default": 50, "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "One page of the withholdings, newest trigger date first; empty when none matches", "content": { "application/json": { "schema": { "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FiscalIslrWithholding" } }, "meta": { "$ref": "#/components/schemas/FiscalIslrWithholdingsMeta" } }, "type": "object", "additionalProperties": false } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "403": { "description": "Missing backoffice.fiscal.withholdings.view", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Forbidden" }, "status": { "type": "integer", "example": 403 }, "detail": { "type": "string", "example": "You do not have permission to access this resource." } }, "type": "object" } } } }, "404": { "description": "company_not_found: the tenant company does not exist", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "error_code": { "type": "string", "example": "company_not_found" } }, "type": "object" } } } }, "422": { "description": "A malformed filter or page, named in `errors`: `month`, `status`, `provider_id`, `purchases_invoice_id`, `page` or `per_page`", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string", "example": "The given data was invalid." }, "errors": { "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" } } } }, "500": { "description": "Internal Server Error, such as a stored withholding whose concept rule is missing from the catalog", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Internal Server Error" }, "status": { "type": "integer", "example": 500 }, "detail": { "type": "string", "example": "An Unexpected Error Occurred" } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/fiscal/igtf-perceived": { "get": { "tags": [ "Backoffice - Fiscal Withholdings" ], "summary": "List the IGTF the company perceived", "description": "The IGTF the company perceived as perception agent on the method lines of its collections (MER-3690, ADR 0193), line by line: its collection and client, the day it was perceived (the day the money was credited, else the collection's day) and its fortnight, the IGTF in the line's currency and in bolívars, and whether a standing `igtf_perceived` withholding remittance paid it to SENIAT (`status` `remitted`, with that remittance, whose id opens `GET fiscal/withholding-remittances/{id}`) or not yet (`pending_remittance`). Cancelled collections, lines that perceived no IGTF and IGTF that rounded to zero never appear. Every filter is optional: `fortnight`, `status` and `client_id`; without `fortnight` every fortnight is read. Rows come newest IGTF day first, then newest collection, then by line position. `meta.counts` and `meta.igtf_ves_by_status` count and total each status under every filter but `status`; `meta.total` and `meta.igtf_ves` respect every filter. The bolívars are those of the whole filtered result, not of the page. A filter nothing matches answers 200 with an empty `data`, zero counts and `0.00` totals, never a 404; another company's lines never appear. Only the query string is read. Paginated by page: `page` from 1, `per_page` 1 to 100 (50 by default). `remittable` is the server's rule for selecting a line into a remittance. Requires `backoffice.fiscal.withholdings.view`.", "operationId": "listFiscalPerceivedIgtf", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "fortnight", "in": "query", "description": "The fortnight the IGTF was perceived in: `YYYY-MM-1` (days 1 to 15) or `YYYY-MM-2` (16 to the month's end).", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])-[12]$", "example": "2026-09-1" } }, { "name": "status", "in": "query", "description": "Only the lines of this status; `meta.counts` and `meta.igtf_ves_by_status` ignore it.", "required": false, "schema": { "type": "string", "enum": [ "pending_remittance", "remitted" ] } }, { "name": "client_id", "in": "query", "description": "Only the lines of this client's collections.", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "description": "The page, from 1.", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Rows a page.", "required": false, "schema": { "type": "integer", "default": 50, "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "One page of the lines, newest IGTF day first; empty when none matches", "content": { "application/json": { "schema": { "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FiscalPerceivedIgtfLine" } }, "meta": { "$ref": "#/components/schemas/FiscalPerceivedIgtfMeta" } }, "type": "object", "additionalProperties": false } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "403": { "description": "Missing backoffice.fiscal.withholdings.view", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Forbidden" }, "status": { "type": "integer", "example": 403 }, "detail": { "type": "string", "example": "You do not have permission to access this resource." } }, "type": "object" } } } }, "404": { "description": "company_not_found: the tenant company does not exist", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "error_code": { "type": "string", "example": "company_not_found" } }, "type": "object" } } } }, "422": { "description": "A malformed filter or page, named in `errors`: `fortnight`, `status`, `client_id`, `page` or `per_page`", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string", "example": "The given data was invalid." }, "errors": { "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" } } } }, "500": { "description": "Internal Server Error, such as a line covered by a remittance that cannot be read (withholding_remittance_missing)", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Internal Server Error" }, "status": { "type": "integer", "example": 500 }, "detail": { "type": "string", "example": "An Unexpected Error Occurred" } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/fiscal/portal-exports/{format}/{period}/download": { "get": { "tags": [ "Backoffice - Fiscal - Portal Exports" ], "summary": "Download a period's Portal Export", "description": "The Portal Export of a format and a period as the file the format version in force on the period's first day writes, generated on demand and never stored (MER-4155). An export with row errors is refused with 422 portal_export_invalid and the same `row_errors` its preview lists, and never written. The production registry ships no version yet, so every period answers 422 portal_export_format_unavailable until the first version is registered (FORM-01). Requires `backoffice.fiscal.withholdings.view`.", "operationId": "downloadFiscalPortalExport", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "format", "in": "path", "description": "A known Portal Export format; an unknown one answers 404 portal_export_format_not_found", "required": true, "schema": { "type": "string", "example": "vat_withholding_txt", "enum": [ "vat_withholding_txt", "islr_withholding_xml" ] } }, { "name": "period", "in": "path", "description": "YYYY-MM-1 or YYYY-MM-2 for VAT withholding TXT; YYYY-MM for ISLR withholding XML", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])(-[12])?$", "example": "2026-09-2" } } ], "responses": { "200": { "description": "The file the version in force writes. Its actual Content-Type is the version's own media type, not application/octet-stream.", "headers": { "Content-Type": { "description": "The version's own media type; a text type always names its charset", "schema": { "type": "string" } }, "Content-Disposition": { "description": "attachment; filename=\"{the version's filename}\"", "schema": { "type": "string" } }, "Cache-Control": { "description": "Always no-store: the file names providers", "schema": { "type": "string", "example": "no-store, private" } } }, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Unauthenticated: the authentication middleware answers before the controller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PortalExportUnauthenticated" } } } }, "403": { "description": "The user lacks backoffice.fiscal.withholdings.view (the route's can: middleware, normalized to the problem envelope with a null error_code), or the company access or tenant membership middleware refuses the request (tenant membership names its reason)", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/PortalExportForbidden" }, { "$ref": "#/components/schemas/PortalExportAccessRefused" } ] } } } }, "404": { "description": "The format is not a known Portal Export format (portal_export_format_not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PortalExportProblem" }, "example": { "title": "Not Found", "status": 404, "detail": " no es un formato de exporte para el portal; los formatos conocidos son: vat_withholding_txt, islr_withholding_xml", "error_code": "portal_export_format_not_found", "errors": null } } } }, "422": { "description": "The period does not match the format (invalid_portal_export_period, with errors.period), no version of the format is in force on its first day (portal_export_format_unavailable), or the export has row errors (portal_export_invalid, with the preview's row_errors): no attachment in any case", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/PortalExportProblem" }, { "$ref": "#/components/schemas/PortalExportFormatUnavailableProblem" }, { "$ref": "#/components/schemas/PortalExportInvalidProblem" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/fiscal/portal-exports/{format}/{period}/preview": { "get": { "tags": [ "Backoffice - Fiscal - Portal Exports" ], "summary": "Preview a period's Portal Export", "description": "The Portal Export of a format and a period as the format version in force on the period's first day would write it, never stored (MER-4155): the version, its validity and specification source, whether a file it wrote was accepted by the portal, the period's days, how many of the period's withholdings it covers (certified, remitted and positive determined ones; never a voided one nor an exclusion at 0 %) and their row errors, the spec-independent ones before the version's own. `downloadable` is the server's rule: today, no row error. An empty period answers zero rows. The production registry ships no version yet, so every period answers 422 portal_export_format_unavailable until the first version is registered (FORM-01). `row_errors` codes and fields are open lists: show `message` for an unknown code. Requires `backoffice.fiscal.withholdings.view`.", "operationId": "previewFiscalPortalExport", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "format", "in": "path", "description": "A known Portal Export format; an unknown one answers 404 portal_export_format_not_found", "required": true, "schema": { "type": "string", "example": "vat_withholding_txt", "enum": [ "vat_withholding_txt", "islr_withholding_xml" ] } }, { "name": "period", "in": "path", "description": "YYYY-MM-1 or YYYY-MM-2 for VAT withholding TXT; YYYY-MM for ISLR withholding XML", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])(-[12])?$", "example": "2026-09-2" } } ], "responses": { "200": { "description": "The period's Portal Export preview", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PortalExportPreview" } } } }, "401": { "description": "Unauthenticated: the authentication middleware answers before the controller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PortalExportUnauthenticated" } } } }, "403": { "description": "The user lacks backoffice.fiscal.withholdings.view (the route's can: middleware, normalized to the problem envelope with a null error_code), or the company access or tenant membership middleware refuses the request (tenant membership names its reason)", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/PortalExportForbidden" }, { "$ref": "#/components/schemas/PortalExportAccessRefused" } ] } } } }, "404": { "description": "The format is not a known Portal Export format (portal_export_format_not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PortalExportProblem" }, "example": { "title": "Not Found", "status": 404, "detail": " no es un formato de exporte para el portal; los formatos conocidos son: vat_withholding_txt, islr_withholding_xml", "error_code": "portal_export_format_not_found", "errors": null } } } }, "422": { "description": "The period does not match the format (invalid_portal_export_period, with errors.period), or no version of the format is in force on its first day (portal_export_format_unavailable): nothing is read either way", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/PortalExportProblem" }, { "$ref": "#/components/schemas/PortalExportFormatUnavailableProblem" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/fiscal/purchase-book/{month}/export": { "get": { "tags": [ "Backoffice - Fiscal - Purchase Book" ], "summary": "Export a month's Purchase Book to Excel", "description": "The same read model as showPurchaseBook as one XLSX sheet «Libro de Compras»: the company's legal name and RIF, the month and each Fiscal Period with its status and the Declared Set version its rows come from; the screen's columns, both dates (Registration Date and emission date; a withholding's trigger date and its certificate's date), «Comprobante de retención» and «IVA retenido» included, plus «Observaciones» (the late mark with the original date); each section's rows in print order, numbered across the month, a practiced VAT withholding on its purchase's row or on its own «RET» row, with its subtotal; an open period's state without rows; and the month's summary of the declared sections. «Exportación», «Otras» and «Sin derecho a crédito fiscal» show only while a figure carries them, as on screen, so the columns after them shift. What the book does not know stays blank. Every amount is a number to the cent, every date an Excel date, every text a string. Named libro-de-compras-{RIF}-{YYYY-MM}.xlsx, or libro-de-compras-{YYYY-MM}.xlsx without a fiscal profile. When some row, subtotal or summary amount exceeds 9999999999999.99 in absolute value or its serialization would not keep the cents, it answers 422 purchase_book_excel_precision_exceeded before any attachment, while showPurchaseBook stays exact. Requires `backoffice.fiscal.fiscal-periods.view`.", "operationId": "exportPurchaseBook", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "month", "in": "path", "description": "A calendar month YYYY-MM", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$", "example": "2026-09" } } ], "responses": { "200": { "description": "The month's Purchase Book as an XLSX attachment", "headers": { "Content-Disposition": { "description": "attachment; filename=\"libro-de-compras-{RIF}-{YYYY-MM}.xlsx\", or libro-de-compras-{YYYY-MM}.xlsx without a fiscal profile", "schema": { "type": "string", "example": "attachment; filename=\"libro-de-compras-J-00000000-0-2026-09.xlsx\"" } }, "Cache-Control": { "description": "Always no-store: the file names providers", "schema": { "type": "string", "example": "no-store, private" } } }, "content": { "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Unauthenticated: the authentication middleware answers before the controller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseBookUnauthenticated" } } } }, "403": { "description": "The user lacks backoffice.fiscal.fiscal-periods.view (the route's can: middleware, normalized to the problem envelope with a null error_code), or the company access or tenant membership middleware refuses the request (tenant membership names its reason)", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/PurchaseBookForbidden" }, { "$ref": "#/components/schemas/PurchaseBookAccessRefused" } ] } } } }, "404": { "description": "The company does not exist (company_not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseBookProblem" }, "example": { "title": "Not Found", "status": 404, "detail": "La empresa con el id … no existe", "error_code": "company_not_found", "errors": null } } } }, "422": { "description": "The month is not a calendar month YYYY-MM (invalid_fiscal_book_month), or Excel cannot hold some amount of the book to the cent (purchase_book_excel_precision_exceeded): no attachment either way", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseBookExportProblem" }, "example": { "title": "Unprocessable Entity", "status": 422, "detail": "No se puede exportar el libro de compras a Excel sin perder precisión. Consulta las cifras exactas en pantalla.", "error_code": "purchase_book_excel_precision_exceeded", "errors": null } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/fiscal/purchase-book/{month}": { "get": { "tags": [ "Backoffice - Fiscal - Purchase Book" ], "summary": "Show a month's Purchase Book", "description": "The month's Purchase Book, built only from the current Declared Set of each of its Fiscal Periods (ADR 0264): one section per period, oldest first (the month alone, or its two fortnights for a special taxpayer, ADR 0265), each with its status, the Declared Set version its rows come from and its subtotals, and the summary of the declared sections. Every declared purchase invoice, supplier credit note (signed negative, naming the purchase it affects) and supplier debit note is one row, placed in the period of its Registration Date and showing its emission date (ADR 0157). A practiced VAT withholding declared in the same set as its purchase shows its VAT withheld and its certificate on that purchase's row; one whose purchase another set declared prints as its own `practiced_vat_withholding` row on its trigger date. A late row keeps its original dates. Every row is numbered across the month. An open period, never frozen, unfrozen or reopened, shows no rows and adds nothing. A month never frozen answers its open sections. Every amount is in bolívares. A purchase whose VAT gives no right to fiscal credit prints that VAT in `non_creditable`, not in its VAT tax columns, and keeps its bases: a purchase invoice marked «Sin derecho a crédito fiscal» with its reason (ADR 0355), or any purchase of a Company whose VAT Taxpayer Type in force on its Registration Date is not ordinary (ADR 0341). Requires `backoffice.fiscal.fiscal-periods.view`.", "operationId": "showPurchaseBook", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "month", "in": "path", "description": "A calendar month YYYY-MM", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$", "example": "2026-09" } } ], "responses": { "200": { "description": "The month's Purchase Book", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseBook" } } } }, "401": { "description": "Unauthenticated: the authentication middleware answers before the controller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseBookUnauthenticated" } } } }, "403": { "description": "The user lacks backoffice.fiscal.fiscal-periods.view (the route's can: middleware, normalized to the problem envelope with a null error_code), or the company access or tenant membership middleware refuses the request (tenant membership names its reason)", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/PurchaseBookForbidden" }, { "$ref": "#/components/schemas/PurchaseBookAccessRefused" } ] } } } }, "404": { "description": "The company does not exist (company_not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseBookProblem" }, "example": { "title": "Not Found", "status": 404, "detail": "La empresa con el id … no existe", "error_code": "company_not_found", "errors": null } } } }, "422": { "description": "The month is not a calendar month YYYY-MM (invalid_fiscal_book_month)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseBookProblem" }, "example": { "title": "Unprocessable Entity", "status": 422, "detail": "<2026-13> no es un mes; se esperaba YYYY-MM, por ejemplo 2026-09", "error_code": "invalid_fiscal_book_month", "errors": null } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/fiscal/purchase-book/{month}/ledger-check": { "get": { "tags": [ "Backoffice - Fiscal - Purchase Book" ], "summary": "Check a month's Purchase Book against the ledger", "description": "Compares, document by document, what the month's Purchase Book declares with what the ledger posted for the same documents (PRD MER-2725), in two blocks. `vat_input`: `book_vat` adds the general, reduced and additional VAT of every purchase invoice and supplier note of the month's declared sections, late rows included, never the VAT withheld; `ledger_vat` adds the functional book's debit − credit, on the account of every VAT Input Account setting of the company whatever its status, and on the accounts of its VAT-kind taxes only while it has no usable VAT Input Account, an active setting whose account and center are active (as posting does, whatever the fiscal profile), of the entries dated in the month that link a purchase invoice, credit note or debit note. `withholdings`: `book_vat` adds the VAT withheld of every practiced VAT withholding the month's declared sections declare, late ones included; `ledger_vat` adds the credit − debit, on the accounts of the company's VAT withholding payable posting accounts whatever their status, of the entries dated in the month that link a VAT withholding (RET). Every document whose two amounts differ is listed with `difference = book_vat − ledger_vat` and its cause, evaluated in this order: `reversal_in_other_month` (its cancellation or voiding reversed it in another month than it was posted in, and the month is one of the two), `late` (a Late Document, in the month that declared it late and in the month its original posting is dated in, ADR 0264), `not_yet_declared` (posted in the month and declared in no current Declared Set, as an open period's documents are) and `unexplained` (anything else). In each block `explained` and `unexplained` add up the differences by cause, signed, so `book_vat − ledger_vat = explained + unexplained`; opposite unexplained differences may net to 0.00, so read whether anything is unexplained from the differences. Every other entry on a block's accounts in the month (a VAT settlement, a remittance, a manual entry, a sale while the tax accounts are read) is listed in its `other_movements`, on the block's side, and never counts. All reads come from one consistent snapshot. A company whose functional currency is not VES answers `available: false` with `unavailable_reason: functional_currency_not_ves` and both blocks with null totals and empty lists. Every amount is in bolívares. Requires `backoffice.fiscal.fiscal-periods.view`.", "operationId": "showPurchaseBookLedgerCheck", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "month", "in": "path", "description": "A calendar month YYYY-MM", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$", "example": "2026-09" } } ], "responses": { "200": { "description": "The month's Purchase Book ledger check, or why the company's ledger cannot be checked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseBookLedgerCheck" } } } }, "401": { "description": "Unauthenticated: the authentication middleware answers before the controller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseBookUnauthenticated" } } } }, "403": { "description": "The user lacks backoffice.fiscal.fiscal-periods.view (the route's can: middleware, normalized to the problem envelope with a null error_code), or the company access or tenant membership middleware refuses the request (tenant membership names its reason)", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/PurchaseBookForbidden" }, { "$ref": "#/components/schemas/PurchaseBookAccessRefused" } ] } } } }, "404": { "description": "The company does not exist (company_not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseBookProblem" }, "example": { "title": "Not Found", "status": 404, "detail": "La empresa con el id … no existe", "error_code": "company_not_found", "errors": null } } } }, "422": { "description": "The month is not a calendar month YYYY-MM (invalid_fiscal_book_month)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseBookProblem" }, "example": { "title": "Unprocessable Entity", "status": 422, "detail": "<2026-13> no es un mes; se esperaba YYYY-MM, por ejemplo 2026-09", "error_code": "invalid_fiscal_book_month", "errors": null } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/fiscal/received-withholdings/{id}/adjustments": { "post": { "tags": [ "Backoffice - Fiscal Withholdings" ], "summary": "Register the client's adjustment of a supported received withholding", "description": "Registers the client's adjustment certificate of the supported received VAT withholding `{id}` (MER-3697, glossary command RegisterReceivedWithholdingAdjustment, ADR 0196 art. 12, ADR 0263): a credit note left an invoice less VAT than the withholding covers, and the client gives part of it back. The adjustment is its own received withholding row of the same client and kind, `supported` with its own certificate — `certificate_number`, `certificate_date` and `received_on`, eligible in the month it was received — that names the original in `corrects_id`, its amounts signed negative. Each line names an invoice the original covers and the bolívars given back, `legal_amount_ves`, negative, at most what the original still withholds from that invoice (`adjustable_ves`); each book restores its share of what the original relieved, `relieved × m ÷ legal` rounded half-up once, and the adjustment that reaches what was withheld takes the exact remainder. In the same transaction, with the invoices locked in ascending id order and then the original: each invoice is owed again what it restored — its `withheld_amount` drops, its balance grows and its status follows; `received_withholding.adjusted` posts dated `received_on`, debiting the receivable at its settlement center and crediting the asset the original's supported entry debited (1.3.03.), any rounding the original posted reversed on its realized account; a pending `review` of the original is resolved by the adjustment, whatever its amount; and the adjustment is written to the audit log as `backoffice.fiscal.received_withholding.adjustment_registered.v1`. The original can no longer be voided while the adjustment stands; void the adjustment first. Only a supported original is adjusted: a reported one answers 409 received_withholding_not_adjustable (void it, or support it first), and so does an adjustment. The client generates the UUID `id`: resending it with the same terms — the original, the trimmed certificate number and date, `received_on` and the same amount per invoice in any order — answers 200 with the adjustment as it stands; with other terms 409 received_withholding_id_conflict. A refusal of one line names it under `errors` as `lines.N.sales_invoice_id` or `lines.N.legal_amount_ves`. Requires `backoffice.fiscal.withholdings.review`; an API key needs the `write` ability.", "operationId": "adjustFiscalReceivedWithholding", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "The supported original received withholding the adjustment corrects.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "id", "certificate_number", "certificate_date", "received_on", "lines" ], "properties": { "id": { "description": "Generated by the client once per adjustment (UUIDv7) and reused on a retry.", "type": "string", "format": "uuid", "example": "0199f1c0-0000-7000-8000-000000000201" }, "certificate_number": { "description": "The client's adjustment certificate number, its own: `AAAAMM` and an eight-digit counter, trimmed — the VAT rule, the only kind adjusted (MER-4197). The original's number answers 409 received_certificate_duplicate.", "type": "string", "pattern": "^\\s*\\d{4}(0[1-9]|1[0-2])\\d{8}\\s*$", "example": "20261000000045" }, "certificate_date": { "description": "The day the adjustment certificate is dated; not after `received_on`.", "type": "string", "format": "date", "example": "2026-10-05" }, "received_on": { "description": "The day the company received it; not after the company's today nor before the day the original's certificate was received.", "type": "string", "format": "date", "example": "2026-10-06" }, "lines": { "description": "The invoices of the original it gives part of the withholding back on, each once.", "type": "array", "items": { "required": [ "sales_invoice_id", "legal_amount_ves" ], "properties": { "sales_invoice_id": { "type": "string", "format": "uuid" }, "legal_amount_ves": { "description": "The bolívars given back of this invoice, negative, with two decimals: no more than the line's `adjustable_ves`.", "type": "string", "pattern": "^-\\d{1,13}\\.\\d{2}$", "example": "-600.00" } }, "type": "object" }, "maxItems": 100, "minItems": 1 } }, "type": "object" } } } }, "responses": { "201": { "description": "Adjustment registered: the adjustment row, without labels", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FiscalReceivedWithholding" } } } }, "200": { "description": "The same request replayed: the adjustment as it stands", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FiscalReceivedWithholding" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "403": { "description": "Missing backoffice.fiscal.withholdings.review, or a read-only API key (api_key_write_ability_required)", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Forbidden" }, "status": { "type": "integer", "example": 403 }, "detail": { "type": "string", "example": "You do not have permission to access this resource." }, "error_code": { "type": "string", "nullable": true, "enum": [ "api_key_write_ability_required" ] } }, "type": "object" } } } }, "404": { "description": "received_withholding_not_found: the company keeps no received withholding `{id}`, another company's included; company_not_found: the tenant company does not exist", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "detail": { "type": "string" }, "error_code": { "type": "string", "enum": [ "received_withholding_not_found", "company_not_found" ] } }, "type": "object" } } } }, "409": { "description": "received_withholding_already_voided: the original is voided; received_withholding_not_adjustable: the original is reported, is itself an adjustment, or is an ISLR withholding, which is not adjusted (MER-2721); received_certificate_duplicate: another supported withholding of the client and kind carries the certificate number, named in `errors` as `certificate_number`; received_withholding_id_conflict: the id is known with other terms. Nothing is written", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "detail": { "type": "string" }, "error_code": { "type": "string", "enum": [ "received_withholding_already_voided", "received_withholding_not_adjustable", "received_certificate_duplicate", "received_withholding_id_conflict" ] }, "errors": { "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" } } } }, "422": { "description": "A malformed field, named in `errors` (a non-negative or zero amount included), or a business rule refused the adjustment, also named in `errors`: received_withholding_adjustment_invoice_not_covered (`lines.N.sales_invoice_id`); received_withholding_adjustment_exceeds_withheld and received_withholding_relief_rounds_to_zero (`lines.N.legal_amount_ves`); received_withholding_dated_in_the_future and received_withholding_adjustment_received_before_original (`received_on`); received_withholding_received_before_certificate (`certificate_date`); an id that is not a UUID (invalid_received_withholding_id). When the company cannot post the entry — a receivable account or center missing, a realized role the reversed rounding needs, a flow not ready for parallel currencies or a closed period — the body is instead `{error: accounting_configuration_incomplete, missing[]}` with no `error_code`. Nothing is written", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string", "example": "El ajuste de Bs 1200.01 supera los Bs 1200.00 que la retención aún retiene de la factura." }, "error_code": { "type": "string", "nullable": true, "enum": [ "received_withholding_adjustment_invoice_not_covered", "received_withholding_adjustment_exceeds_withheld", "received_withholding_relief_rounds_to_zero", "received_withholding_dated_in_the_future", "received_withholding_adjustment_received_before_original", "received_withholding_received_before_certificate", "invalid_received_withholding_id", "invalid_received_certificate_number", "invalid_received_withholding" ] }, "errors": { "description": "The offending request fields, each with its messages.", "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "error": { "description": "Only on an accounting readiness gap, which carries `missing` instead of the fields above.", "type": "string", "enum": [ "accounting_configuration_incomplete" ] }, "missing": { "description": "Only on an accounting readiness gap: every gap that keeps the entry from posting.", "type": "array", "items": { "required": [ "reason_code", "subject_type", "subject_id", "human_message", "details" ], "properties": { "reason_code": { "type": "string", "example": "ACCOUNTING_PERIOD_CLOSED", "enum": [ "RECEIVABLE_ACCOUNT_MISSING", "RECEIVABLE_ACCOUNT_INACTIVE", "RECEIVABLE_CENTER_MISSING", "EXCHANGE_POSTING_ACCOUNT_MISSING", "LEDGER_FLOW_NOT_PARALLEL_CURRENCY_READY", "ACCOUNTING_PERIOD_CLOSED" ] }, "subject_type": { "type": "string", "example": "company" }, "subject_id": { "type": "string" }, "human_message": { "type": "string" }, "details": { "type": "array", "items": { "type": "string" } } }, "type": "object" } } }, "type": "object" } } } }, "500": { "description": "Internal server error, such as an original whose entry is missing (received_withholding_posted_transaction_missing) or carries no single asset (received_withholding_posted_asset_not_found), an invoice that refuses the restoration (sales_invoice_received_withholding_integrity), an entry that would not balance (invalid_transaction_balance) or a ledger write that failed (transaction_persistence_failed); nothing is written", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Internal Server Error" }, "status": { "type": "integer", "example": 500 }, "detail": { "type": "string", "example": "An Unexpected Error Occurred" }, "error_code": { "type": "string", "nullable": true } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/fiscal/received-withholdings/{id}": { "get": { "tags": [ "Backoffice - Fiscal Withholdings" ], "summary": "Read a received withholding", "description": "A withholding a client practised on the company and the company registered (MER-3692): the client's certificate, the bolívars it withheld and what each sales invoice it covers gave up in each book, naming its client (`client_name`) and each invoice (`sales_invoice_code`), null when the company does not keep it (MER-3696). Another company's reads as not found. Requires `backoffice.fiscal.withholdings.view`.", "operationId": "getFiscalReceivedWithholding", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "The received withholding id.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The received withholding", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FiscalReceivedWithholding" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "403": { "description": "Missing backoffice.fiscal.withholdings.view", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Forbidden" }, "status": { "type": "integer", "example": 403 }, "detail": { "type": "string", "example": "You do not have permission to access this resource." } }, "type": "object" } } } }, "404": { "description": "received_withholding_not_found: the company keeps no received withholding with this id, another company's included", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "detail": { "type": "string" }, "error_code": { "type": "string", "enum": [ "received_withholding_not_found" ] } }, "type": "object" } } } }, "422": { "description": "invalid_received_withholding_id: the id is not a UUID", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string" }, "error_code": { "type": "string", "enum": [ "invalid_received_withholding_id" ] } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/fiscal/received-withholdings": { "get": { "tags": [ "Backoffice - Fiscal Withholdings" ], "summary": "List the received withholdings, or read the ones pending at a cut-off day", "description": "The withholdings clients practised on the company and the company registered (MER-3694, MER-3696), each as it stands, with its lines. Every filter is optional: `status`, `kind` (`vat` or `islr`, MER-3706), `client_id`, `sales_invoice_id` (the withholdings with a line on that invoice, MER-3695), `eligibility_period` (the month a supported withholding is eligible in) and `review=pending` (the VAT withholdings a credit note flagged for review and nobody resolved, MER-3697). An adjustment of a VAT withholding (MER-3697) is listed as its own row, `corrects_id` naming its original, its amounts signed negative, and counts and totals as one: `summary.total_bs` and `summary.count` are signed nets, so with `eligibility_period` alone the total can be negative. With `as_of`, only allowed with `status=reported`, it reads the withholdings pending at the end of that day — received by then and neither supported nor voided until after it, the documentary items the guided close of that period reads (V14, non-blocking) — and each row's `status` still shows where it stands now. A withholding registered with its certificate is never pending. The pending read follows what received withholdings moved through `reported_withholding_pending` (1.3.05.) by that day; a manual entry on that account is not part of it. `summary` counts and totals in bolívars every row the filters match, over every page, and `meta.total` is that same count; it totals every line of each matching withholding, so with `sales_invoice_id` it includes their lines on other invoices too, and without `kind` it adds VAT and ISLR bolívars. `meta.counts` counts each status under every filter but `status` and `as_of` (`kind` and `review` included), naming `reported`, `supported` and `voided` even at zero, and `review_pending`, always present, counts the withholdings pending review under every filter but `review`; `meta.kind_counts` counts each kind under every filter but `kind` (`review` included), naming `vat` and `islr` even at zero; `meta.clients` offers every client of the company with a received withholding, whatever the filters, by name (MER-3696). Each row names its client (`client_name`), each line its invoice (`sales_invoice_code`) and its `review` its credit note and invoice (`credit_note_code`, `sales_invoice_code`), null when the company does not keep it; the write answers do not, so refetch after supporting or voiding. A filter nothing matches answers 200 with an empty `data` and a zero summary, never a 404; another company's withholdings never appear. Only the query string is read. Rows come newest `received_on` first, then newest registered, then by id, so pages never repeat nor skip a row. Paginated by page: `page` from 1, `per_page` 1 to 100 (50 by default). `supportable`, `voidable` and `adjustable` are the server's rules for offering «Soportar», «Anular» and «Registrar ajuste»; an ISLR withholding is never `adjustable` nor reviewed. Statuses are lower case; treat one you do not know as neither supportable nor voidable. Requires `backoffice.fiscal.withholdings.view`.", "operationId": "listFiscalReceivedWithholdings", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "description": "Only the withholdings that stand in this status; with `as_of` it must be `reported`.", "required": false, "schema": { "type": "string", "enum": [ "reported", "supported", "voided" ] } }, { "name": "kind", "in": "query", "description": "Only the withholdings of this kind (MER-3706): `vat` or `islr`.", "required": false, "schema": { "type": "string", "enum": [ "vat", "islr" ] } }, { "name": "client_id", "in": "query", "description": "Only the withholdings of this client.", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "sales_invoice_id", "in": "query", "description": "Only the withholdings with a line on this sales invoice (MER-3695), as the invoice record's «Retenciones recibidas» reads them. Each row still lists every line it has, those on other invoices included.", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "eligibility_period", "in": "query", "description": "Only the withholdings eligible in this month, `YYYY-MM`: the month their certificate was received.", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$", "example": "2026-11" } }, { "name": "as_of", "in": "query", "description": "The cut-off day of the pending read; only with `status=reported`.", "required": false, "schema": { "type": "string", "format": "date", "example": "2026-10-31" } }, { "name": "review", "in": "query", "description": "Only the withholdings whose review stands in this state: `pending`, flagged by a credit note and not yet resolved (MER-3697). Combines with every other filter.", "required": false, "schema": { "type": "string", "enum": [ "pending" ] } }, { "name": "page", "in": "query", "description": "The page, from 1.", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Rows a page.", "required": false, "schema": { "type": "integer", "default": 50, "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "One page of the withholdings, newest received first, with the summary of every row the filters match; empty when none matches", "content": { "application/json": { "schema": { "required": [ "data", "meta", "summary" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FiscalReceivedWithholding" } }, "meta": { "$ref": "#/components/schemas/FiscalReceivedWithholdingsMeta" }, "summary": { "$ref": "#/components/schemas/FiscalReceivedWithholdingsSummary" } }, "type": "object", "additionalProperties": false } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "403": { "description": "Missing backoffice.fiscal.withholdings.view", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Forbidden" }, "status": { "type": "integer", "example": 403 }, "detail": { "type": "string", "example": "You do not have permission to access this resource." } }, "type": "object" } } } }, "404": { "description": "company_not_found: the tenant company does not exist", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "error_code": { "type": "string", "example": "company_not_found" } }, "type": "object" } } } }, "422": { "description": "A malformed filter or page, named in `errors`: `status`, `kind`, `client_id`, `sales_invoice_id`, `eligibility_period`, `as_of` (also when given without `status=reported`), `review`, `page` or `per_page`", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string", "example": "The given data was invalid." }, "errors": { "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" } } } }, "500": { "description": "Internal Server Error, such as a stored withholding the domain refuses to rebuild (received_withholding_row_corrupt)", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Internal Server Error" }, "status": { "type": "integer", "example": 500 }, "detail": { "type": "string", "example": "An Unexpected Error Occurred" } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Fiscal Withholdings" ], "summary": "Register a received VAT or ISLR withholding, supported or reported", "description": "Registers the VAT (`kind` `vat`) a client that is a special taxpayer, or the ISLR (`kind` `islr`) a client that is an ISLR withholding agent, withheld from the company's sales invoices (MER-3692, MER-3694, MER-3706, glossary command RegisterReceivedWithholding, ADR 0190, 0194). With the certificate the client handed over, `certificate_number` and `certificate_date`, it is `supported`; without them, both absent or null, the client only reported it and it is `reported` until `POST fiscal/received-withholdings/{id}/support` supports it (one without the other is 422). Each line names an approved regular sales invoice of `client_id`, or for `vat` an approved Sales Debit Note of it (ADR 0371), and the bolívars withheld from it, `legal_amount_ves`: from its VAT for `vat`, capped by that VAT in bolívars; from its taxable base for `islr`, every tax group's base net of discount and without VAT, capped by that base in bolívars. The legal amount wins (ADR 0126): the invoice gives up the same share of its VAT, `vat_document × legal_amount_ves ÷ vat_ves`, or of its taxable base, `base_document × legal_amount_ves ÷ base_ves`, in its Document Currency, rounded half-up once, its functional book the legal amount's value, and its reporting book its share; a line that settles the invoice gives up every book's remainder. No collection is recorded: the invoice's `withheld_amount` grows by what it gave up, and it is to be collected while `balance ≥ total − withheld_amount`. In the same transaction `received_withholding.registered` posts dated `received_on`: the kind's supported account, `vat_withholding_supported` (1.3.03.) or `islr_withholding_supported` (1.3.04.), for a supported one, or `reported_withholding_pending` (1.3.05.) for a reported one, which is no fiscal credit and has no eligibility period, is debited with the legal amount and each invoice's receivable credited with what it gave up at its settlement center; functional rounding of a settling line posts as a realized gain or loss. The invoices are locked in ascending id order, like a collection's. A certificate number is supported once per client and kind, so a client's VAT and ISLR certificates may share one; an `islr` withholding never warns `client_not_special_taxpayer`. An invoice a withholding relieved cannot be cancelled (409 sales_invoice_has_received_withholding) until the withholding is voided. The registration is written to the audit log as `backoffice.fiscal.received_withholding.registered.v1`. The client generates the UUID `id`: resending it with the same terms — client, kind, the certificate number as its kind reads it and its date (or none), `received_on` and the same legal amount per invoice in any order — answers 200 with the withholding as it stands now, supported or voided since included, and no warnings; with other terms 409 received_withholding_id_conflict. A refusal of one line names it under `errors` as `lines.N.sales_invoice_id` or `lines.N.legal_amount_ves`, N being its position in the request. Requires `backoffice.fiscal.received-withholdings.register`; an API key needs the `write` ability.", "operationId": "registerFiscalReceivedWithholding", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "id", "client_id", "kind", "received_on", "lines" ], "properties": { "id": { "description": "Generated by the client once per withholding (UUIDv7) and reused on a retry.", "type": "string", "format": "uuid", "example": "0199e0a0-0000-7000-8000-000000000101" }, "client_id": { "description": "The client that withheld; every invoice must be its own.", "type": "string", "format": "uuid" }, "kind": { "description": "What the client withheld: `vat` from the invoices' VAT, `islr` from their taxable base. A retry under the same `id` resends the same kind.", "type": "string", "enum": [ "vat", "islr" ] }, "certificate_number": { "description": "The client's certificate number, read by `kind` (MER-4197): `vat`, `AAAAMM` and an eight-digit counter, trimmed; `islr`, the client's own numbering (Decreto 1.808 art. 24), trimmed, inner runs of spaces collapsed to one, 1 to 30 characters, no control characters — one that does not follow `AAAAMM` + 8 registers with the warning `certificate_number_not_digital_format`. Stored and answered as its kind reads it. One certificate of a client and kind is supported once, compared regardless of letter case and accents. Absent or null, with `certificate_date`, for a reported withholding.", "type": "string", "example": "20260900000123", "nullable": true }, "certificate_date": { "description": "The day the certificate is dated; not after `received_on`. Absent or null, with `certificate_number`, for a reported withholding.", "type": "string", "format": "date", "example": "2026-09-05", "nullable": true }, "received_on": { "description": "The day the company received it; not after the company's today nor before any invoice's emission date.", "type": "string", "format": "date", "example": "2026-09-05" }, "lines": { "description": "The sales invoices it withholds from, each once; for `vat`, its approved debit notes too.", "type": "array", "items": { "required": [ "sales_invoice_id", "legal_amount_ves" ], "properties": { "sales_invoice_id": { "type": "string", "format": "uuid" }, "legal_amount_ves": { "description": "The bolívars withheld from this invoice's VAT (`vat`) or taxable base (`islr`), positive, with two decimals: no more than that VAT or base in bolívars nor than what it still owes.", "type": "string", "pattern": "^\\d{1,13}\\.\\d{2}$", "example": "1200.00" } }, "type": "object" }, "maxItems": 100, "minItems": 1 } }, "type": "object" } } } }, "responses": { "201": { "description": "Received withholding registered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FiscalReceivedWithholdingRegistration" } } } }, "200": { "description": "The same request replayed: the withholding as it stands, with no warnings", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FiscalReceivedWithholdingRegistration" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "403": { "description": "Missing backoffice.fiscal.received-withholdings.register, or a read-only API key (api_key_write_ability_required)", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Forbidden" }, "status": { "type": "integer", "example": 403 }, "detail": { "type": "string", "example": "You do not have permission to access this resource." }, "error_code": { "type": "string", "nullable": true, "enum": [ "api_key_write_ability_required" ] } }, "type": "object" } } } }, "404": { "description": "company_not_found: the tenant company does not exist", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "detail": { "type": "string" }, "error_code": { "type": "string", "enum": [ "company_not_found" ] } }, "type": "object" } } } }, "409": { "description": "received_certificate_duplicate: another supported withholding of the same client and kind carries this certificate number, named in `errors` as `certificate_number`; received_withholding_id_conflict: the id is known with other terms. Nothing is written", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "detail": { "type": "string", "example": "El comprobante 20260900000123 ya está registrado para este cliente." }, "error_code": { "type": "string", "enum": [ "received_certificate_duplicate", "received_withholding_id_conflict" ] }, "errors": { "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" } } } }, "422": { "description": "A malformed field, named in `errors` (a certificate number without its date, or a date without its number, included), or a business rule refused the withholding, also named in `errors`: received_withholding_invoice_not_found (the company keeps no regular invoice with this id, or for `vat` no debit note: another company's, a credit note, an opening document, or a debit note under `islr`), received_withholding_client_mismatch, received_withholding_invoice_not_open (a draft or cancelled regular invoice or debit note), received_withholding_invoice_without_vat (`vat`: no VAT, or its VAT unknown in bolívars or in the functional book) and received_withholding_invoice_without_base (`islr`: no taxable base in bolívars or in the functional book) (`lines.N.sales_invoice_id`); received_withholding_exceeds_vat (`vat`), received_withholding_exceeds_base (`islr`), withholding_exceeds_open_balance (a fully collected invoice answers it too) and received_withholding_relief_rounds_to_zero (`lines.N.legal_amount_ves`); received_withholding_dated_in_the_future and received_withholding_dated_before_invoice (`received_on`); received_withholding_received_before_certificate (`certificate_date`). When the company cannot post the entry — a receivable account or center missing, the kind's supported account (`vat_withholding_supported` or `islr_withholding_supported`) or, for a reported one, `reported_withholding_pending` missing (FISCAL_ACCOUNT_MISSING), a realized role a rounding line needs, a flow not ready for parallel currencies or a closed period — the body is instead `{error: accounting_configuration_incomplete, missing[]}` with no `error_code`. Nothing is written", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string", "example": "La retención aliviaría 1200.00, más que el saldo pendiente de 1000.00 de la factura." }, "error_code": { "type": "string", "nullable": true, "enum": [ "received_withholding_invoice_not_found", "received_withholding_client_mismatch", "received_withholding_invoice_not_open", "received_withholding_invoice_without_vat", "received_withholding_invoice_without_base", "received_withholding_exceeds_vat", "received_withholding_exceeds_base", "withholding_exceeds_open_balance", "received_withholding_relief_rounds_to_zero", "received_withholding_dated_in_the_future", "received_withholding_dated_before_invoice", "received_withholding_received_before_certificate", "invalid_received_withholding_id", "invalid_received_certificate_number", "invalid_received_withholding" ] }, "errors": { "description": "The offending request fields, each with its messages.", "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "error": { "description": "Only on an accounting readiness gap, which carries `missing` instead of the fields above.", "type": "string", "enum": [ "accounting_configuration_incomplete" ] }, "missing": { "description": "Only on an accounting readiness gap: every gap that keeps the entry from posting.", "type": "array", "items": { "required": [ "reason_code", "subject_type", "subject_id", "human_message", "details" ], "properties": { "reason_code": { "type": "string", "example": "FISCAL_ACCOUNT_MISSING", "enum": [ "FISCAL_ACCOUNT_MISSING", "RECEIVABLE_ACCOUNT_MISSING", "RECEIVABLE_ACCOUNT_INACTIVE", "RECEIVABLE_CENTER_MISSING", "EXCHANGE_POSTING_ACCOUNT_MISSING", "LEDGER_FLOW_NOT_PARALLEL_CURRENCY_READY", "ACCOUNTING_PERIOD_CLOSED" ] }, "subject_type": { "type": "string", "example": "company" }, "subject_id": { "type": "string" }, "human_message": { "type": "string" }, "details": { "type": "array", "items": { "type": "string" } } }, "type": "object" } } }, "type": "object" } } } }, "500": { "description": "Internal server error, such as a relief the invoice refuses (sales_invoice_received_withholding_integrity), an entry that would not balance (invalid_transaction_balance, empty_transaction_items) or a ledger write that failed (transaction_persistence_failed); nothing is written", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Internal Server Error" }, "status": { "type": "integer", "example": 500 }, "detail": { "type": "string", "example": "An Unexpected Error Occurred" }, "error_code": { "type": "string", "nullable": true } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/fiscal/received-withholdings/{id}/support": { "post": { "tags": [ "Backoffice - Fiscal Withholdings" ], "summary": "Support a reported received withholding with its certificate", "description": "The client's certificate of a reported withholding arrived (MER-3694, glossary command SupportReceivedWithholding, ADR 0194): the withholding becomes `supported` and is eligible in the month the certificate was received (`eligibility_period`, V08: the period of receipt is kept, whatever month its invoices were emitted in). Here `received_on` is the day the certificate was received, stored and answered as `certificate_received_on`: no earlier than the day the withholding was reported nor than the day the certificate is dated, and no later than the company's today. In the same transaction `received_withholding.supported` posts dated that day, moving the amounts its registration parked in `reported_withholding_pending` (1.3.05.) to the kind's supported account (1.3.03. `vat_withholding_supported` for VAT, 1.3.04. `islr_withholding_supported` for ISLR); and the support is written to the audit log as `backoffice.fiscal.received_withholding.supported.v1` with who supported it. A certificate number is supported once per client and kind, compared regardless of letter case and accents: one another supported withholding carries answers 409 received_certificate_duplicate, named in `errors` as `certificate_number`. Unlike the registration it answers no `warnings`: an `islr` number that does not follow `AAAAMM` + 8 is supported as is. A supported withholding answers 409 received_withholding_already_supported and a voided one 409 received_withholding_already_voided; a retry after a lost response answers 409 too, so read the withholding to confirm it. Nothing is written on a refusal. Requires `backoffice.fiscal.withholdings.review`; an API key needs the `write` ability.", "operationId": "supportFiscalReceivedWithholding", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "The received withholding id.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "certificate_number", "certificate_date", "received_on" ], "properties": { "certificate_number": { "description": "The client's certificate number, which follows the withholding's kind (MER-4197): `vat`, `AAAAMM` and an eight-digit counter, trimmed; `islr`, the client's own numbering (Decreto 1.808 art. 24), trimmed, inner runs of spaces collapsed to one, 1 to 30 characters, no control characters. Stored and answered as the kind reads it.", "type": "string", "example": "20261100000045" }, "certificate_date": { "description": "The day the certificate is dated; not after `received_on`.", "type": "string", "format": "date", "example": "2026-11-01" }, "received_on": { "description": "The day the company received the certificate, whose month the withholding is eligible in.", "type": "string", "format": "date", "example": "2026-11-03" } }, "type": "object" } } } }, "responses": { "200": { "description": "Received withholding supported", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FiscalReceivedWithholding" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "403": { "description": "Missing backoffice.fiscal.withholdings.review, or a read-only API key (api_key_write_ability_required)", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Forbidden" }, "status": { "type": "integer", "example": 403 }, "detail": { "type": "string", "example": "You do not have permission to access this resource." }, "error_code": { "type": "string", "nullable": true, "enum": [ "api_key_write_ability_required" ] } }, "type": "object" } } } }, "404": { "description": "received_withholding_not_found: the company keeps no received withholding with this id, another company's included; company_not_found: the tenant company does not exist", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "detail": { "type": "string" }, "error_code": { "type": "string", "enum": [ "received_withholding_not_found", "company_not_found" ] } }, "type": "object" } } } }, "409": { "description": "received_withholding_already_supported: it is supported already; received_withholding_already_voided: it was voided; received_certificate_duplicate: another supported withholding of the same client and kind carries this certificate number, named in `errors` as `certificate_number`. Nothing is written", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "detail": { "type": "string", "example": "La retención recibida ya está soportada." }, "error_code": { "type": "string", "enum": [ "received_withholding_already_supported", "received_withholding_already_voided", "received_certificate_duplicate" ] }, "errors": { "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" } } } }, "422": { "description": "A malformed field, named in `errors`, or a business rule refused the support, also named in `errors`: received_withholding_dated_in_the_future and received_withholding_supported_before_reported (`received_on`); received_withholding_received_before_certificate (`certificate_date`); invalid_received_certificate_number (`certificate_number`: the withholding's kind does not read it, as a `vat` one that does not follow `AAAAMM` + 8; it is checked once the withholding is found, so an unknown id answers 404 first, while a number no kind reads — empty, longer than 30 characters or with a control character — fails validation with no `error_code`); invalid_received_withholding_id. When the company cannot post the reclassification — the kind's supported account (`vat_withholding_supported` or `islr_withholding_supported`) or `reported_withholding_pending` missing (FISCAL_ACCOUNT_MISSING), a flow not ready for parallel currencies or the period of `received_on` closed — the body is instead `{error: accounting_configuration_incomplete, missing[]}` with no `error_code`. Nothing is written", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string", "example": "El comprobante recibido el 2026-10-19 es anterior a la retención informada el 2026-10-20." }, "error_code": { "type": "string", "nullable": true, "enum": [ "received_withholding_dated_in_the_future", "received_withholding_supported_before_reported", "received_withholding_received_before_certificate", "invalid_received_withholding_id", "invalid_received_certificate_number" ] }, "errors": { "description": "The offending request fields, each with its messages.", "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "error": { "description": "Only on an accounting readiness gap, which carries `missing` instead of the fields above.", "type": "string", "enum": [ "accounting_configuration_incomplete" ] }, "missing": { "description": "Only on an accounting readiness gap: every gap that keeps the reclassification from posting.", "type": "array", "items": { "required": [ "reason_code", "subject_type", "subject_id", "human_message", "details" ], "properties": { "reason_code": { "type": "string", "example": "ACCOUNTING_PERIOD_CLOSED", "enum": [ "FISCAL_ACCOUNT_MISSING", "LEDGER_FLOW_NOT_PARALLEL_CURRENCY_READY", "ACCOUNTING_PERIOD_CLOSED" ] }, "subject_type": { "type": "string", "example": "company" }, "subject_id": { "type": "string" }, "human_message": { "type": "string" }, "details": { "type": "array", "items": { "type": "string" } } }, "type": "object" } } }, "type": "object" } } } }, "500": { "description": "Internal server error, such as a reclassification that would not balance (invalid_transaction_balance, empty_transaction_items) or a ledger write that failed (transaction_persistence_failed); nothing is written", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Internal Server Error" }, "status": { "type": "integer", "example": 500 }, "detail": { "type": "string", "example": "An Unexpected Error Occurred" }, "error_code": { "type": "string", "nullable": true } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/fiscal/received-withholdings/{id}/void": { "post": { "tags": [ "Backoffice - Fiscal Withholdings" ], "summary": "Void a received withholding", "description": "Voids a reported or supported received withholding, or an adjustment of one (MER-3694, MER-3697, glossary command VoidReceivedWithholding, ADR 0190, 0213), with a reason. In the same transaction: a plain read learns the sales invoices it covers, which are locked first in ascending id order, the order a collection and a credit note's approval lock them in, and only then the withholding (an adjustment's original first, then the adjustment). An original gets each invoice back exactly what it relieved in each book, so its `withheld_amount` drops, its balance grows and its status follows (an invoice with no collection is `to_be_collected` again, and can be cancelled once nothing is withheld from it); each entry it posted is reversed, newest first, by its own `received_withholding.voided` dated the company's today that names the entry it reverses and inverts every line in every book — a reported then supported one reverses its `received_withholding.supported` reclassification and then its registration, so the receivable is owed again and neither 1.3.05. nor the kind's supported account (1.3.03. VAT, 1.3.04. ISLR) keeps anything; a pending `review` is resolved by the voiding. An original with a standing adjustment answers 409 received_withholding_has_standing_adjustment: void the adjustment first. An adjustment of a VAT withholding (`corrects_id` set) relieves each invoice again by what it restored — refused with 409 received_withholding_adjustment_not_voidable when an invoice no longer owes that in every book, collected or credited since — reverses only its `received_withholding.adjusted` entry, and reopens the original's review it resolved. The voiding is written to the audit log as `backoffice.fiscal.received_withholding.voided.v1` with who voided it and why. A voided withholding frees its certificate number, so it can support another registration. A voided one answers 409 received_withholding_already_voided and nothing is written. One the current Declared Set of a Fiscal Period in review or closed holds, an adjustment included, which a period declares on its own, answers 409 document_in_frozen_fiscal_period after the plain read and before anything is locked, naming the period in `fiscal_period` (MER-3837); registering an adjustment is never refused for it. A blank reason, or one longer than 500 characters once trimmed, answers the validator's 422 with `errors.reason` (the domain's invalid_received_withholding_void_reason guards the same rule and is not expected on the wire). Requires `backoffice.fiscal.withholdings.review`; an API key needs the `write` ability.", "operationId": "voidFiscalReceivedWithholding", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "The received withholding id.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "reason" ], "properties": { "reason": { "description": "Why it is voided: 1 to 500 characters once trimmed; inner line breaks are kept.", "type": "string", "example": "Comprobante emitido a otra factura", "maxLength": 500, "minLength": 1 } }, "type": "object" } } } }, "responses": { "200": { "description": "Received withholding voided, with `voiding`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FiscalReceivedWithholding" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "403": { "description": "Missing backoffice.fiscal.withholdings.review, or a read-only API key (api_key_write_ability_required)", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Forbidden" }, "status": { "type": "integer", "example": 403 }, "detail": { "type": "string", "example": "You do not have permission to access this resource." }, "error_code": { "type": "string", "nullable": true, "enum": [ "api_key_write_ability_required" ] } }, "type": "object" } } } }, "404": { "description": "received_withholding_not_found: the company keeps no received withholding with this id, another company's included; company_not_found: the tenant company does not exist", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "detail": { "type": "string" }, "error_code": { "type": "string", "enum": [ "received_withholding_not_found", "company_not_found" ] } }, "type": "object" } } } }, "409": { "description": "received_withholding_already_voided: the withholding is already voided; received_withholding_has_standing_adjustment: an adjustment of the original still stands; received_withholding_adjustment_not_voidable: an invoice the adjustment restored no longer owes it in every book; document_in_frozen_fiscal_period: a frozen fiscal period declared it, with `fiscal_period` (MER-3837). Nothing is written", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "detail": { "type": "string", "example": "La retención recibida ya está anulada." }, "error_code": { "type": "string", "enum": [ "received_withholding_already_voided", "received_withholding_has_standing_adjustment", "received_withholding_adjustment_not_voidable", "document_in_frozen_fiscal_period" ] }, "fiscal_period": { "description": "Only on document_in_frozen_fiscal_period: the period whose current Declared Set holds the withholding.", "allOf": [ { "$ref": "#/components/schemas/FrozenFiscalPeriod" } ] } }, "type": "object" } } } }, "422": { "description": "A blank or too long reason (`errors.reason`), or an id that is not a UUID (invalid_received_withholding_id); nothing is written", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string" }, "error_code": { "type": "string", "nullable": true, "enum": [ "invalid_received_withholding_id", "invalid_received_withholding_void_reason" ] }, "errors": { "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" } } } }, "500": { "description": "The voiding could not restore the debt or reverse the entries (received_withholding_posted_transaction_missing, received_withholding_missing for an adjustment whose original is gone, transaction_already_reversed, sales_invoice_received_withholding_integrity, invalid_transaction_balance, empty_transaction_items or transaction_persistence_failed); nothing is written", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Internal Server Error" }, "status": { "type": "integer", "example": 500 }, "detail": { "type": "string", "example": "An Unexpected Error Occurred" }, "error_code": { "type": "string", "nullable": true } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/fiscal/sales-book/{month}/export": { "get": { "tags": [ "Backoffice - Fiscal - Sales Book" ], "summary": "Export a month's Sales Book to Excel", "description": "The same read model as showSalesBook as one XLSX sheet «Libro de Ventas»: the company's legal name and RIF, the month and each Fiscal Period with its status and the Declared Set version its rows come from; the screen's columns plus «Observaciones» (the late and cancelled marks and a withholding certificate's date); each section's rows in print order, numbered across the month, with its subtotal; an open period's state without rows; and the month's summary of the declared sections. «Otras» shows only while a figure carries it, as on screen. Every amount is a number to the cent, every date an Excel date, every text a string. Named libro-de-ventas-{RIF}-{YYYY-MM}.xlsx, or libro-de-ventas-{YYYY-MM}.xlsx without a fiscal profile. When some row, subtotal or summary amount exceeds 9999999999999.99 in absolute value or its serialization would not keep the cents, it answers 422 sales_book_excel_precision_exceeded before any attachment, while showSalesBook stays exact. Requires `backoffice.fiscal.fiscal-periods.view`.", "operationId": "exportSalesBook", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "month", "in": "path", "description": "A calendar month YYYY-MM", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$", "example": "2026-09" } } ], "responses": { "200": { "description": "The month's Sales Book as an XLSX attachment", "headers": { "Content-Disposition": { "description": "attachment; filename=\"libro-de-ventas-{RIF}-{YYYY-MM}.xlsx\", or libro-de-ventas-{YYYY-MM}.xlsx without a fiscal profile", "schema": { "type": "string", "example": "attachment; filename=\"libro-de-ventas-J-00000000-0-2026-09.xlsx\"" } }, "Cache-Control": { "description": "Always no-store: the file names customers", "schema": { "type": "string", "example": "no-store, private" } } }, "content": { "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Unauthenticated: the authentication middleware answers before the controller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesBookUnauthenticated" } } } }, "403": { "description": "The user lacks backoffice.fiscal.fiscal-periods.view (the route's can: middleware, normalized to the problem envelope with a null error_code), or the company access or tenant membership middleware refuses the request (tenant membership names its reason)", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/SalesBookForbidden" }, { "$ref": "#/components/schemas/SalesBookAccessRefused" } ] } } } }, "404": { "description": "The company does not exist (company_not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesBookProblem" }, "example": { "title": "Not Found", "status": 404, "detail": "La empresa con el id … no existe", "error_code": "company_not_found", "errors": null } } } }, "422": { "description": "The month is not a calendar month YYYY-MM (invalid_fiscal_book_month), or Excel cannot hold some amount of the book to the cent (sales_book_excel_precision_exceeded): no attachment either way", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesBookExportProblem" }, "example": { "title": "Unprocessable Entity", "status": 422, "detail": "No se puede exportar el libro de ventas a Excel sin perder precisión. Consulta las cifras exactas en pantalla.", "error_code": "sales_book_excel_precision_exceeded", "errors": null } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/fiscal/sales-book/{month}": { "get": { "tags": [ "Backoffice - Fiscal - Sales Book" ], "summary": "Show a month's Sales Book", "description": "The month's Sales Book, built only from the current Declared Set of each of its Fiscal Periods (ADR 0264): one section per period, oldest first (the month alone, or its two fortnights for a special taxpayer, ADR 0265), each with its status, the Declared Set version its rows come from and its subtotals, and the summary of the declared sections. Every declared sales invoice, credit note (signed negative, naming the document it affects) and debit note is one row, except that each day's active, on-time, numbered invoices whose buyer froze as a VAT non-taxpayer print as one Non-Taxpayer Daily Summary row with their first and last number, count and summed amounts; a late document keeps its original Book Date, and a cancelled one shows zero amounts. Each declared line of a supported received VAT withholding prints as its own row on the day its certificate arrived, after that day's documents, carrying only the VAT withheld, which the subtotals and the summary add apart from sales; a reported withholding never prints. Every row is numbered across the month. An open period, never frozen, unfrozen or reopened, shows no rows and adds nothing. A month never frozen answers its open sections. Every amount is in bolívares. Requires `backoffice.fiscal.fiscal-periods.view`.", "operationId": "showSalesBook", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "month", "in": "path", "description": "A calendar month YYYY-MM", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$", "example": "2026-09" } } ], "responses": { "200": { "description": "The month's Sales Book", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesBook" } } } }, "401": { "description": "Unauthenticated: the authentication middleware answers before the controller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesBookUnauthenticated" } } } }, "403": { "description": "The user lacks backoffice.fiscal.fiscal-periods.view (the route's can: middleware, normalized to the problem envelope with a null error_code), or the company access or tenant membership middleware refuses the request (tenant membership names its reason)", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/SalesBookForbidden" }, { "$ref": "#/components/schemas/SalesBookAccessRefused" } ] } } } }, "404": { "description": "The company does not exist (company_not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesBookProblem" }, "example": { "title": "Not Found", "status": 404, "detail": "La empresa con el id … no existe", "error_code": "company_not_found", "errors": null } } } }, "422": { "description": "The month is not a calendar month YYYY-MM (invalid_fiscal_book_month)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesBookProblem" }, "example": { "title": "Unprocessable Entity", "status": 422, "detail": "<2026-13> no es un mes; se esperaba YYYY-MM, por ejemplo 2026-09", "error_code": "invalid_fiscal_book_month", "errors": null } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/fiscal/sales-book/{month}/ledger-check": { "get": { "tags": [ "Backoffice - Fiscal - Sales Book" ], "summary": "Check a month's Sales Book against the ledger", "description": "Compares, document by document, the output VAT the month's Sales Book declares with the output VAT the ledger posted for the same documents (PRD MER-2724). `book_vat` adds the general, reduced and additional VAT of every sales invoice and note of the month's declared sections, late rows included: the VAT columns of the book's summary; an open period adds nothing. `ledger_vat` adds the functional book's credit − debit, on the accounts of the company's VAT-kind taxes, of the entries dated in the month that link a sales invoice, credit note or debit note. Every document whose two amounts differ is listed with `difference = book_vat − ledger_vat` and its cause, evaluated in this order: `reversal_in_other_month` (its cancellation reversed it in another month than it was posted in, and the month is one of the two), `late` (a Late Document, in the month that declared it late and in the month its original posting is dated in, ADR 0264), `not_yet_declared` (posted in the month and declared in no current Declared Set, as an open period's documents are) and `unexplained` (anything else). `explained` and `unexplained` add up the differences by cause, signed, so `book_vat − ledger_vat = explained + unexplained`; opposite unexplained differences may net to 0.00, so read whether anything is unexplained from the differences. Every other entry on those accounts in the month (a VAT settlement, a manual entry, a collection) is listed in `other_movements`, credit − debit, and never counts. All reads come from one consistent snapshot. A company whose functional currency is not VES answers `available: false` with `unavailable_reason: functional_currency_not_ves`, null totals and empty lists. Every amount is in bolívares. Requires `backoffice.fiscal.fiscal-periods.view`.", "operationId": "showSalesBookLedgerCheck", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "month", "in": "path", "description": "A calendar month YYYY-MM", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$", "example": "2026-09" } } ], "responses": { "200": { "description": "The month's Sales Book ledger check, or why the company's ledger cannot be checked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesBookLedgerCheck" } } } }, "401": { "description": "Unauthenticated: the authentication middleware answers before the controller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesBookUnauthenticated" } } } }, "403": { "description": "The user lacks backoffice.fiscal.fiscal-periods.view (the route's can: middleware, normalized to the problem envelope with a null error_code), or the company access or tenant membership middleware refuses the request (tenant membership names its reason)", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/SalesBookForbidden" }, { "$ref": "#/components/schemas/SalesBookAccessRefused" } ] } } } }, "404": { "description": "The company does not exist (company_not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesBookProblem" }, "example": { "title": "Not Found", "status": 404, "detail": "La empresa con el id … no existe", "error_code": "company_not_found", "errors": null } } } }, "422": { "description": "The month is not a calendar month YYYY-MM (invalid_fiscal_book_month)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesBookProblem" }, "example": { "title": "Unprocessable Entity", "status": 422, "detail": "<2026-13> no es un mes; se esperaba YYYY-MM, por ejemplo 2026-09", "error_code": "invalid_fiscal_book_month", "errors": null } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/fiscal/tax-declarations/{id}": { "get": { "tags": [ "Backoffice - Fiscal - Tax Declarations" ], "summary": "Read a tax declaration dossier by id", "description": "Returns every version of the obligation that owns this id, including when the id is a replaced version. Another company's id answers 404. Requires `backoffice.fiscal.declarations.view`.", "operationId": "getTaxDeclarationDossier", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The dossier", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxDeclarationDossier" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Missing backoffice.fiscal.declarations.view" }, "404": { "description": "tax_declaration_not_found" }, "422": { "description": "The id is not a UUID" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/fiscal/tax-declarations/{id}/payment": { "post": { "tags": [ "Backoffice - Fiscal - Tax Declarations" ], "summary": "Record payment of a tax declaration", "description": "Records either a cash payment or the recorded withholding remittances that paid the return (MER-4152). The two shapes are exclusive. Requires `backoffice.fiscal.declarations.manage`.", "operationId": "payTaxDeclaration", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "paid_on": { "type": "string", "format": "date", "nullable": true }, "paid_ves": { "type": "string", "pattern": "^\\d{1,13}\\.\\d{2}$", "example": "10.00", "nullable": true }, "payment_reference": { "type": "string", "nullable": true, "maxLength": 120, "minLength": 1 }, "withholding_remittance_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "nullable": true, "minItems": 1, "uniqueItems": true } }, "type": "object" } } } }, "responses": { "200": { "description": "The paid dossier", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxDeclarationDossier" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Missing backoffice.fiscal.declarations.manage" }, "404": { "description": "tax_declaration_not_found" }, "409": { "description": "tax_declaration_not_current or tax_declaration_already_paid" }, "422": { "description": "payment_shape_invalid or remittance_not_of_declaration" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/fiscal/tax-declarations": { "get": { "tags": [ "Backoffice - Fiscal - Tax Declarations" ], "summary": "Search a tax declaration dossier", "description": "Returns the current declaration and every version of one obligation. An obligation with no rows answers current null and versions empty. Requires `backoffice.fiscal.declarations.view`.", "operationId": "searchTaxDeclarationDossier", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "kind", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "vat", "vat_withholding", "islr_withholding", "igtf_perceived" ] } }, { "name": "period", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])(-[12])?$", "example": "2026-09-1" } } ], "responses": { "200": { "description": "The dossier", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxDeclarationDossier" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Missing backoffice.fiscal.declarations.view" }, "422": { "description": "kind or period is malformed" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Fiscal - Tax Declarations" ], "summary": "File a tax declaration", "description": "Records version 1 of a return filed outside Backoffice (MER-4152). A zero payable stays filed. VAT carry-forward amounts are required only for vat. Requires `backoffice.fiscal.declarations.manage`.", "operationId": "registerTaxDeclaration", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "kind", "period", "period_type", "return_number", "filed_on", "payable_ves" ], "properties": { "kind": { "type": "string", "enum": [ "vat", "vat_withholding", "islr_withholding", "igtf_perceived" ] }, "period": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])(-[12])?$", "example": "2026-09-1" }, "period_type": { "type": "string", "enum": [ "month", "fortnight" ] }, "return_number": { "type": "string", "example": "12345678", "maxLength": 40, "minLength": 1 }, "filed_on": { "type": "string", "format": "date", "example": "2026-09-24" }, "payable_ves": { "type": "string", "pattern": "^\\d{1,13}\\.\\d{2}$", "example": "0.00" }, "carried_excess_ves": { "type": "string", "pattern": "^\\d{1,13}\\.\\d{2}$", "example": "0.00", "nullable": true }, "carried_withholdings_ves": { "type": "string", "pattern": "^\\d{1,13}\\.\\d{2}$", "example": "0.00", "nullable": true }, "notes": { "type": "string", "nullable": true, "maxLength": 500 } }, "type": "object" } } } }, "responses": { "201": { "description": "The filed dossier", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxDeclarationDossier" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Missing backoffice.fiscal.declarations.manage" }, "404": { "description": "company_not_found" }, "409": { "description": "tax_declaration_already_filed" }, "422": { "description": "period_type_mismatch, fiscal_period_not_frozen, carry_forward_only_on_vat, filed_on_after_today, or validation" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/fiscal/tax-declarations/{id}/replace": { "post": { "tags": [ "Backoffice - Fiscal - Tax Declarations" ], "summary": "File a substitute tax declaration", "description": "Files the next version and marks the current row replaced (MER-4152). The previous version stays readable. Requires `backoffice.fiscal.declarations.manage`.", "operationId": "replaceTaxDeclaration", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "kind", "period", "period_type", "return_number", "filed_on", "payable_ves" ], "properties": { "kind": { "type": "string", "enum": [ "vat", "vat_withholding", "islr_withholding", "igtf_perceived" ] }, "period": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])(-[12])?$", "example": "2026-09-1" }, "period_type": { "type": "string", "enum": [ "month", "fortnight" ] }, "return_number": { "type": "string", "maxLength": 40, "minLength": 1 }, "filed_on": { "type": "string", "format": "date" }, "payable_ves": { "type": "string", "pattern": "^\\d{1,13}\\.\\d{2}$", "example": "0.00" }, "carried_excess_ves": { "type": "string", "pattern": "^\\d{1,13}\\.\\d{2}$", "nullable": true }, "carried_withholdings_ves": { "type": "string", "pattern": "^\\d{1,13}\\.\\d{2}$", "nullable": true }, "notes": { "type": "string", "nullable": true, "maxLength": 500 } }, "type": "object" } } } }, "responses": { "201": { "description": "The dossier, newest version first", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxDeclarationDossier" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Missing backoffice.fiscal.declarations.manage" }, "404": { "description": "tax_declaration_not_found" }, "409": { "description": "tax_declaration_not_current" }, "422": { "description": "The same filing refusals as register" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/fiscal/tax-obligations": { "get": { "tags": [ "Backoffice - Fiscal - Tax Obligations" ], "summary": "List derived tax obligations for a month range", "description": "Derives the company's Tax Obligations from the Company Tax Attributes held on any day of each period, the RIF check digit, and the global Tax Calendar (MER-4149, MER-5666, CAL-01). Due dates are never invented: unverified or missing calendar versions answer due_on null. Requires `backoffice.fiscal.declarations.view`.", "operationId": "searchTaxObligations", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "description": "Inclusive first month YYYY-MM", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$", "example": "2026-10" } }, { "name": "to", "in": "query", "description": "Inclusive last month YYYY-MM (span at most 12 months)", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$", "example": "2026-10" } } ], "responses": { "200": { "description": "Derived obligations (may be empty with a reason)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxObligationsResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "403": { "description": "Missing backoffice.fiscal.declarations.view", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Forbidden" }, "status": { "type": "integer", "example": 403 }, "detail": { "type": "string", "example": "You do not have permission to access this resource." } }, "type": "object" } } } }, "404": { "description": "company_not_found", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "error_code": { "type": "string", "example": "company_not_found" } }, "type": "object" } } } }, "422": { "description": "Invalid from/to, inverted range, or span greater than 12 months", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "error_code": { "type": "string", "example": "invalid_tax_obligations_range", "nullable": true } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/fiscal/tax-units": { "get": { "tags": [ "Backoffice - Fiscal Rules" ], "summary": "Read the tax unit in force on a date", "description": "A find over the global tax units catalog (PA SNAT/2025/000048): the value in bolívares of the SENIAT tax unit (UT) in force on `date` for the tenant's country, the unit ISLR minimum bases and subtractors are stated in. The catalog is global: the tenant only decides which country's unit is read, and every tenant sees the same rows. A day before the first unit, or on or after a suspension, answers 422 `rule_not_in_force`: the unit is never extrapolated.", "operationId": "b3377213bf2ccf1031f0209e27cb6670", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "date", "in": "query", "description": "Day the unit must be in force on, exactly Y-m-d. Required.", "required": true, "schema": { "type": "string", "format": "date", "example": "2025-06-02" } } ], "responses": { "200": { "description": "The tax unit in force on `date`", "content": { "application/json": { "schema": { "required": [ "date", "country", "tax_unit" ], "properties": { "date": { "type": "string", "format": "date", "example": "2025-06-02" }, "country": { "description": "ISO 3166-1 alpha-2 country of the tenant", "type": "string", "example": "VE" }, "tax_unit": { "$ref": "#/components/schemas/FiscalTaxUnit" } }, "type": "object", "additionalProperties": false } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "403": { "description": "Missing backoffice.fiscal.rules.view", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Forbidden" }, "status": { "type": "integer", "example": 403 }, "detail": { "type": "string", "example": "You do not have permission to access this resource." } }, "type": "object" } } } }, "404": { "description": "company_not_found: the tenant company does not exist", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "error_code": { "type": "string", "example": "company_not_found" } }, "type": "object" } } } }, "422": { "description": "`date` is missing or is not an existing Y-m-d day (`errors` names it, `error_code` is null); or no tax unit is in force on `date` (`error_code` rule_not_in_force, `errors` is null)", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string", "example": "La regla del catálogo tax_units de no está vigente el <2025-06-01>" }, "error_code": { "type": "string", "example": "rule_not_in_force", "nullable": true, "enum": [ "rule_not_in_force" ] }, "errors": { "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Internal Server Error" }, "status": { "type": "integer", "example": 500 }, "detail": { "type": "string", "example": "An Unexpected Error Occurred" } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/fiscal/vat-withholding-rates": { "get": { "tags": [ "Backoffice - Fiscal Rules" ], "summary": "List the VAT withholding rules in force on a date, grouped by kind", "description": "A search over the global VAT withholding rates catalog (PA SNAT/2025/000054): the rules every company of the tenant's country may apply to a taxable event on `date`. Always answers the three groups `standard`, `full` and `exclusion`, each in natural code order (`art3_n2` before `art3_n10`); a group is empty when no rule of its kind is in force, for example before 2025-08-01 — never a 404. A suspended rule is left out from its suspension date on. The catalog is global: the tenant only decides which country's rules are read, and every tenant sees the same rows. Not paginated.", "operationId": "b0ca2a60b4da11358bf9175c16371bcb", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "date", "in": "query", "description": "Day of the taxable event, exactly Y-m-d. Required.", "required": true, "schema": { "type": "string", "format": "date", "example": "2025-09-15" } } ], "responses": { "200": { "description": "The rules in force on `date`, grouped by kind", "content": { "application/json": { "schema": { "required": [ "date", "country", "standard", "full", "exclusion" ], "properties": { "date": { "type": "string", "format": "date", "example": "2025-09-15" }, "country": { "description": "ISO 3166-1 alpha-2 country of the tenant", "type": "string", "example": "VE" }, "standard": { "description": "The general rate (art. 4)", "type": "array", "items": { "$ref": "#/components/schemas/FiscalVatWithholdingRate" } }, "full": { "description": "The art. 5 causes for 100 %", "type": "array", "items": { "$ref": "#/components/schemas/FiscalVatWithholdingRate" } }, "exclusion": { "description": "The art. 3 exclusions for 0 %", "type": "array", "items": { "$ref": "#/components/schemas/FiscalVatWithholdingRate" } } }, "type": "object", "additionalProperties": false } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "403": { "description": "Missing backoffice.fiscal.rules.view", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Forbidden" }, "status": { "type": "integer", "example": 403 }, "detail": { "type": "string", "example": "You do not have permission to access this resource." } }, "type": "object" } } } }, "404": { "description": "company_not_found: the tenant company does not exist", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "error_code": { "type": "string", "example": "company_not_found" } }, "type": "object" } } } }, "422": { "description": "`date` is missing or is not an existing Y-m-d day", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string", "example": "The given data was invalid." }, "errors": { "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Internal Server Error" }, "status": { "type": "integer", "example": 500 }, "detail": { "type": "string", "example": "An Unexpected Error Occurred" } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/fiscal/vat-withholdings/{id}/void": { "post": { "tags": [ "Backoffice - Fiscal Withholdings" ], "summary": "Void a VAT withholding", "description": "Voids a VAT withholding the company practised and has not remitted (MER-3110, glossary command VoidPracticedWithholding, ADR 0196), with a reason. In the same transaction: the purchases invoice owes the provider again exactly what the withholding relieved in each book (its `withheld_amount` goes back to 0.00 and its balance and status follow), its certificate is voided and keeps its number, `vat_withholding.voided` posts dated the company's today inverting every line of its `vat_withholding.determined` entry in both books (an exclusion at 0 % posted nothing and reverses nothing), and the voiding is written to the audit log as `backoffice.fiscal.vat_withholding.voided.v1` with who voided it and why. A voided withholding answers 409 vat_withholding_already_voided and a remitted one 409 remitted_withholding_requires_adjustment (MER-3111, ADR 0196: it is corrected under art. 12); one the current Declared Set of a Fiscal Period in review or closed holds answers 409 document_in_frozen_fiscal_period first, before anything is locked, naming the period in `fiscal_period` (MER-3837); nothing is written. A blank reason, or one longer than 500 characters once trimmed, answers the validator's 422 with `errors.reason` (the domain's invalid_vat_withholding_void_reason guards the same rule and is not expected on the wire). Cancelling the purchases invoice voids its withholding the same way, with the reason «Factura cancelada». Requires `backoffice.fiscal.withholdings.review`; an API key needs the `write` ability.", "operationId": "voidFiscalVatWithholding", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "The withholding id.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "reason" ], "properties": { "reason": { "description": "Why it is voided: 1 to 500 characters once trimmed; inner line breaks are kept.", "type": "string", "example": "Monto mal calculado; se reemitirá.", "maxLength": 500, "minLength": 1 } }, "type": "object" } } } }, "responses": { "200": { "description": "Withholding voided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FiscalVatWithholdingVoidResult" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "403": { "description": "Missing backoffice.fiscal.withholdings.review, or a read-only API key (api_key_write_ability_required)", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Forbidden" }, "status": { "type": "integer", "example": 403 }, "detail": { "type": "string", "example": "You do not have permission to access this resource." }, "error_code": { "type": "string", "nullable": true, "enum": [ "api_key_write_ability_required" ] } }, "type": "object" } } } }, "404": { "description": "vat_withholding_not_found: the company keeps no withholding with this id, another company's included", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "detail": { "type": "string" }, "error_code": { "type": "string", "enum": [ "vat_withholding_not_found", "company_not_found" ] } }, "type": "object" } } } }, "409": { "description": "vat_withholding_already_voided: the withholding is already voided; remitted_withholding_requires_adjustment: it was remitted to SENIAT, so it is corrected with an adjustment in a later period (art. 12, MER-3111) — void its remittance first while that is still possible; document_in_frozen_fiscal_period: a frozen fiscal period declared it, with `fiscal_period` (MER-3837). Nothing is written", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "detail": { "type": "string", "example": "La retención de IVA ya está anulada." }, "error_code": { "type": "string", "enum": [ "vat_withholding_already_voided", "remitted_withholding_requires_adjustment", "document_in_frozen_fiscal_period" ] }, "fiscal_period": { "description": "Only on document_in_frozen_fiscal_period: the period whose current Declared Set holds the withholding.", "allOf": [ { "$ref": "#/components/schemas/FrozenFiscalPeriod" } ] } }, "type": "object" } } } }, "422": { "description": "A blank or too long reason (`errors.reason`), or an id that is not a UUID (invalid_vat_withholding_id); nothing is written", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string" }, "error_code": { "type": "string", "nullable": true, "enum": [ "invalid_vat_withholding_id", "invalid_vat_withholding_void_reason" ] }, "errors": { "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" } } } }, "500": { "description": "The voiding could not restore the debt or mirror the entry (vat_withholding_posted_transaction_missing, transaction_already_reversed, invalid_transaction_balance, empty_transaction_items, transaction_persistence_failed, purchases_invoice_withholding_restore_failed or purchases_invoice_persistence_failed); nothing is written", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Internal Server Error" }, "status": { "type": "integer", "example": 500 }, "detail": { "type": "string", "example": "An Unexpected Error Occurred" }, "error_code": { "type": "string", "nullable": true } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/fiscal/vat-withholdings": { "get": { "tags": [ "Backoffice - Fiscal Withholdings" ], "summary": "List the VAT withholdings the company practised", "description": "The VAT withholdings the company practised as withholding agent (MER-3109, MER-3110, PA SNAT/2025/000054), each named by its purchases invoice and provider, with the rule it applied and its label, the reason that supports a cause, the amounts, a summary of the certificate that certifies or certified it (whose id opens `GET fiscal/withholding-certificates/{id}`; a voided withholding shows its voided certificate, which keeps its number), why, when and by whom it was voided, whether a payment dated before its registration suggests an earlier trigger date (`trigger_date_superseded`, with the suggested day and fortnight; `trigger_date` and `fortnight` never change), and the remittance that paid it to SENIAT (MER-3111: `remittance`, the one not voided, whose id opens `GET fiscal/withholding-remittances/{id}`). Every filter is optional: `fortnight`, `status`, `provider_id` and `purchases_invoice_id`, which keeps the read of one invoice's withholdings of MER-3109; without `fortnight` every fortnight is read. Rows come newest `trigger_date` first, then newest created, then by id, so pages never repeat nor skip a row. `meta.counts` counts each status under every filter but `status`, naming `determined`, `certified`, `remitted` and `voided` even at zero, and `meta.total` respects every filter. A filter nothing matches answers 200 with an empty `data` and zero counts, never a 404; another company's withholdings never appear. Only the query string is read. Paginated by page: `page` from 1, `per_page` 1 to 100 (50 by default). `voidable` is the server's rule for offering «Anular» and `remittable` for selecting it into a remittance (only `certified` ones). Statuses are lower case; treat one you do not know as neither voidable nor remittable. Requires `backoffice.fiscal.withholdings.view`.", "operationId": "listFiscalVatWithholdings", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "fortnight", "in": "query", "description": "The fortnight the withholdings are declared in: `YYYY-MM-1` (days 1 to 15) or `YYYY-MM-2` (16 to the month's end).", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])-[12]$", "example": "2026-09-2" } }, { "name": "status", "in": "query", "description": "Only the withholdings of this status; `meta.counts` ignores it.", "required": false, "schema": { "type": "string", "enum": [ "determined", "certified", "remitted", "voided" ] } }, { "name": "provider_id", "in": "query", "description": "Only the withholdings practised on this provider.", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "purchases_invoice_id", "in": "query", "description": "Only the withholdings practised on this purchases invoice.", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "description": "The page, from 1.", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Rows a page.", "required": false, "schema": { "type": "integer", "default": 50, "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "One page of the withholdings, newest trigger date first; empty when none matches", "content": { "application/json": { "schema": { "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FiscalVatWithholding" } }, "meta": { "$ref": "#/components/schemas/FiscalVatWithholdingsMeta" } }, "type": "object", "additionalProperties": false } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "403": { "description": "Missing backoffice.fiscal.withholdings.view", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Forbidden" }, "status": { "type": "integer", "example": 403 }, "detail": { "type": "string", "example": "You do not have permission to access this resource." } }, "type": "object" } } } }, "404": { "description": "company_not_found: the tenant company does not exist", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "error_code": { "type": "string", "example": "company_not_found" } }, "type": "object" } } } }, "422": { "description": "A malformed filter or page, named in `errors`: `fortnight`, `status`, `provider_id`, `purchases_invoice_id`, `page` or `per_page`", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string", "example": "The given data was invalid." }, "errors": { "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" } } } }, "500": { "description": "Internal Server Error, such as a stored withholding whose catalog rule is missing", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Internal Server Error" }, "status": { "type": "integer", "example": 500 }, "detail": { "type": "string", "example": "An Unexpected Error Occurred" } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/fiscal/vat-workpapers/{period}": { "get": { "tags": [ "Backoffice - Fiscal - VAT Workpapers" ], "summary": "Show the VAT workpaper of a frozen fiscal period", "description": "Computes the VAT Workpaper from the current Declared Set of a frozen Fiscal Period: débitos, créditos, cuota / excess and withholdings application, preferring a prior filed VAT Tax Declaration when present (MER-4147, MER-4153, ADR 0264 / 0285). When the current period has a filed declaration that diverges from the workpaper, `filed_differs` is true. Practiced withholdings are reported only. Requires `backoffice.fiscal.fiscal-periods.view`.", "operationId": "showVatWorkpaper", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "period", "in": "path", "description": "A month YYYY-MM or a fortnight YYYY-MM-1 or YYYY-MM-2", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])(-[12])?$", "example": "2026-09-1" } } ], "responses": { "200": { "description": "The computed VAT workpaper", "content": { "application/json": { "schema": { "required": [ "period", "status", "declared_set_version", "currency", "carry_forward_source", "carry_forward_declaration_id", "prior_period", "debits", "credits", "prior_excess", "positive_quota", "excess_to_carry", "received_withholdings", "carried_withholdings", "available_withholdings", "used_withholdings", "vat_payable", "withholdings_to_carry", "practiced_withholdings", "filed_differs", "filed_differences" ], "properties": { "period": { "type": "string", "example": "2026-09-1" }, "status": { "type": "string", "example": "closed", "enum": [ "in_review", "closed" ] }, "declared_set_version": { "type": "integer", "example": 1 }, "currency": { "type": "string", "example": "VES" }, "carry_forward_source": { "type": "string", "example": "none", "enum": [ "none", "computed_workpaper", "filed_declaration" ] }, "carry_forward_declaration_id": { "description": "Id of the prior current VAT Tax Declaration when carry_forward_source is filed_declaration; otherwise null", "type": "string", "format": "uuid", "example": null, "nullable": true }, "prior_period": { "type": "string", "example": null, "nullable": true }, "debits": { "properties": { "amount": { "type": "string", "example": "4400.00" }, "documents": { "$ref": "#/components/schemas/VatWorkpaperDocumentsFilter" } }, "type": "object" }, "credits": { "properties": { "amount": { "type": "string", "example": "3680.00" }, "documents": { "$ref": "#/components/schemas/VatWorkpaperDocumentsFilter" } }, "type": "object" }, "prior_excess": { "properties": { "amount": { "type": "string", "example": "0.00" }, "prior_period": { "type": "string", "nullable": true } }, "type": "object" }, "positive_quota": { "properties": { "amount": { "type": "string", "example": "720.00" } }, "type": "object" }, "excess_to_carry": { "properties": { "amount": { "type": "string", "example": "0.00" } }, "type": "object" }, "received_withholdings": { "properties": { "amount": { "type": "string", "example": "1200.00" }, "documents": { "$ref": "#/components/schemas/VatWorkpaperDocumentsFilter" } }, "type": "object" }, "carried_withholdings": { "properties": { "amount": { "type": "string", "example": "0.00" }, "prior_period": { "type": "string", "nullable": true } }, "type": "object" }, "available_withholdings": { "properties": { "amount": { "type": "string", "example": "1200.00" } }, "type": "object" }, "used_withholdings": { "properties": { "amount": { "type": "string", "example": "720.00" } }, "type": "object" }, "vat_payable": { "properties": { "amount": { "type": "string", "example": "0.00" } }, "type": "object" }, "withholdings_to_carry": { "properties": { "amount": { "type": "string", "example": "480.00" } }, "type": "object" }, "practiced_withholdings": { "properties": { "amount": { "type": "string", "example": "2760.00" }, "documents": { "$ref": "#/components/schemas/VatWorkpaperDocumentsFilter" } }, "type": "object" }, "filed_differs": { "description": "True when the current period has a filed|paid VAT declaration whose payable / carried figures diverge from this workpaper", "type": "boolean", "example": false }, "filed_differences": { "description": "Filed vs workpaper amount pairs when filed_differs is true; otherwise null", "properties": { "payable_ves": { "properties": { "filed": { "type": "string", "example": "160.00" }, "workpaper": { "type": "string", "example": "480.00" } }, "type": "object" }, "carried_excess_ves": { "properties": { "filed": { "type": "string", "example": "0.00" }, "workpaper": { "type": "string", "example": "0.00" } }, "type": "object" }, "carried_withholdings_ves": { "properties": { "filed": { "type": "string", "example": "500.00" }, "workpaper": { "type": "string", "example": "480.00" } }, "type": "object" } }, "type": "object", "example": null, "nullable": true } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks the view permission" }, "404": { "description": "The company does not exist (company_not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FiscalPeriodProblem" }, "example": { "title": "Not Found", "status": 404, "detail": "La empresa con el id … no existe", "error_code": "company_not_found", "errors": null } } } }, "409": { "description": "The period is open or was never frozen (fiscal_period_not_frozen)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FiscalPeriodProblem" }, "example": { "title": "Conflict", "status": 409, "detail": "El período fiscal <2026-09-1> no está congelado, así que no tiene papel de trabajo de IVA", "error_code": "fiscal_period_not_frozen", "errors": null } } } }, "422": { "description": "The period is malformed (errors.period), or the company declares the month by the other type (fiscal_period_type_mismatch)", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/FiscalPeriodValidationProblem" }, { "$ref": "#/components/schemas/FiscalPeriodProblem" } ] }, "example": { "title": "Unprocessable Entity", "status": 422, "detail": "La empresa declara el mes de <2026-09> por períodos de tipo fortnight, así que <2026-09> no es uno de sus períodos fiscales", "error_code": "fiscal_period_type_mismatch", "errors": null, "expected_period_type": "fortnight" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/fiscal/withholding-certificates/{id}/delivery": { "post": { "tags": [ "Backoffice - Fiscal Withholdings" ], "summary": "Record that a withholding certificate reached its provider", "description": "Records when and through which channel the certificate reached its provider, which is what lets the provider deduct what was withheld (MER-3108, PA 2025/000054 art. 16). A certificate is delivered once: the same instant and channel again — in any offset, by any user — answers 200 and changes nothing, keeping who recorded it first; another delivery answers 409. The instant cannot be in the future nor before the company's day of issuance. While the company's withholding certificates are not validated (`validation_locked: true` on the certificate, pending MER-2751), a new delivery answers 422 withholding_certificate_delivery_locked and writes nothing; the same delivery already recorded still answers 200, and a voided or otherwise delivered certificate still answers 409. Requires `backoffice.fiscal.withholding-certificates.issue`; an API key needs the `write` ability.", "operationId": "02d3258e86c01914c9c9fabaddd60f13", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "The certificate id.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "delivered_at", "channel" ], "properties": { "delivered_at": { "description": "RFC 3339 instant with its offset, to the second.", "type": "string", "format": "date-time", "example": "2026-10-01T10:30:00-04:00" }, "channel": { "type": "string", "example": "email", "enum": [ "email", "whatsapp", "in_person", "provider_portal" ] } }, "type": "object" } } } }, "responses": { "200": { "description": "Delivery recorded, or the same delivery recorded again" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "403": { "description": "Missing backoffice.fiscal.withholding-certificates.issue, or a read-only API key (api_key_write_ability_required)", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Forbidden" }, "status": { "type": "integer", "example": 403 }, "detail": { "type": "string", "example": "You do not have permission to access this resource." }, "error_code": { "type": "string", "nullable": true, "enum": [ "api_key_write_ability_required" ] } }, "type": "object" } } } }, "404": { "description": "withholding_certificate_not_found: the company keeps no certificate with this id, another company's included", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "detail": { "type": "string" }, "error_code": { "type": "string", "enum": [ "withholding_certificate_not_found" ] } }, "type": "object" } } } }, "409": { "description": "The certificate was already delivered otherwise (withholding_certificate_already_delivered) or is voided (withholding_certificate_voided); nothing is written.", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "detail": { "type": "string" }, "error_code": { "type": "string", "enum": [ "withholding_certificate_already_delivered", "withholding_certificate_voided" ] } }, "type": "object" } } } }, "422": { "description": "`delivered_at` or `channel` is missing or malformed (`errors`), the id is not a UUID (invalid_withholding_certificate_id), the company's withholding certificates are not validated yet (withholding_certificate_delivery_locked), or the delivery is in the future or before the company's day of issuance (invalid_certificate_delivery); nothing is written.", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string" }, "error_code": { "type": "string", "nullable": true, "enum": [ "invalid_withholding_certificate_id", "invalid_certificate_delivery", "invalid_certificate_delivery_channel", "withholding_certificate_delivery_locked" ] }, "errors": { "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/fiscal/withholding-certificates/{id}": { "get": { "tags": [ "Backoffice - Fiscal Withholdings" ], "summary": "Read a withholding certificate as it prints", "description": "The numbered VAT or ISLR withholding certificate the company issued, as withholding agent, when it approved the purchase it withheld from (MER-3108, MER-3701, PA 2025/000054 art. 16): its number in the series of its kind, the agent and the provider as they stood on issuance, the withholdings it certifies — an ISLR one concept by concept — its delivery, and whether the company's certificates are still locked pending validation (`validation_locked`, MER-3718). A withholding that withholds nothing — a VAT exclusion at 0 % or an ISLR withholding below every minimum — has none. Requires `backoffice.fiscal.withholdings.view`.", "operationId": "949f344ebd6a3d4245856ef6959a0626", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "The certificate id.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The certificate", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FiscalWithholdingCertificate" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "403": { "description": "Missing backoffice.fiscal.withholdings.view", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Forbidden" }, "status": { "type": "integer", "example": 403 }, "detail": { "type": "string", "example": "You do not have permission to access this resource." } }, "type": "object" } } } }, "404": { "description": "withholding_certificate_not_found: the company keeps no certificate with this id, another company's included", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "detail": { "type": "string" }, "error_code": { "type": "string", "enum": [ "withholding_certificate_not_found" ] } }, "type": "object" } } } }, "422": { "description": "invalid_withholding_certificate_id: the id is not a UUID", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string" }, "error_code": { "type": "string", "enum": [ "invalid_withholding_certificate_id" ] } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/fiscal/withholding-remittances/{id}": { "get": { "tags": [ "Backoffice - Fiscal Withholdings" ], "summary": "Read a withholding remittance", "description": "A withholding remittance the company recorded (MER-3111, MER-3690, MER-3703): what it paid to SENIAT of each VAT or ISLR withholding or of each collection method line's perceived IGTF, by kind, through which instrument and bank reference, and its voiding, if any. Another company's reads as not found. Requires `backoffice.fiscal.withholdings.view`.", "operationId": "getFiscalWithholdingRemittance", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "The remittance id.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The remittance", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FiscalWithholdingRemittance" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "403": { "description": "Missing backoffice.fiscal.withholdings.view", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Forbidden" }, "status": { "type": "integer", "example": 403 }, "detail": { "type": "string", "example": "You do not have permission to access this resource." } }, "type": "object" } } } }, "404": { "description": "withholding_remittance_not_found: the company keeps no remittance with this id, another company's included", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "detail": { "type": "string" }, "error_code": { "type": "string", "enum": [ "withholding_remittance_not_found" ] } }, "type": "object" } } } }, "422": { "description": "invalid_withholding_remittance_id: the id is not a UUID", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string" }, "error_code": { "type": "string", "enum": [ "invalid_withholding_remittance_id" ] } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/fiscal/withholding-remittances": { "post": { "tags": [ "Backoffice - Fiscal Withholdings" ], "summary": "Record a withholding remittance", "description": "Records the payment to SENIAT of VAT withholdings the company practised (`kind: vat_withholding`, MER-3111), of the IGTF it perceived on collection method lines (`kind: igtf_perceived`, MER-3690) or of ISLR withholdings it practised (`kind: islr_withholding`, MER-3703), glossary command RecordWithholdingRemittance, ADR 0196. Each kind is remitted by its own period: a fortnight `YYYY-MM-1` / `YYYY-MM-2` for `vat_withholding` and `igtf_perceived`, a month `YYYY-MM` for `islr_withholding`; a period of the other shape answers the validator's 422 with `errors.period`. A `vat_withholding` remittance names `withholding_ids`, never `collection_method_line_ids`: every withholding named must be `certified` and of the fortnight `period`, and becomes `remitted`; from then on it is corrected under art. 12 instead of voided, and the purchases invoice it was practised on cannot be cancelled. A fortnight may be remitted in several remittances, each withholding in one. The money leaves through `payment_instrument_id`, an active instrument of the company in bolívars whose treasury account is active; the instrument, its treasury account and that account's accounting account are frozen on the remittance. In the same transaction `withholding_remittance.recorded` posts dated `remitted_on`: `vat_withholding_payable` (2.2.02) is debited with the bolívars paid and, in each book, exactly what the withholdings' determinations credited there, and the instrument's accounting account is credited with the bolívars and, in a book that does not keep bolívars, the share of the bank's carrying amount they relieve; every gap with the official value of the money and of the debt at the official USD/VES rate of `remitted_on` posts as a realized `debt_currency` or `treasury_currency` gain or loss in its own book, every line on the center of the 2.2.02 role. An `igtf_perceived` remittance names `collection_method_line_ids`, never `withholding_ids`: every line named must belong to a collection of the company that is not cancelled, have perceived an IGTF that did not round to zero, on a day (the day its money was credited, else the collection's day) of the fortnight `period`, valued in a functional book that keeps bolívars (422 perceived_igtf_not_valued_in_bolivares otherwise); it pays all the bolívars the line credited to `igtf_payable` (2.2.04), and the line reads `remitted` while the remittance stands, which blocks cancelling its collection (409 remitted_igtf_requires_adjustment there). Its entry debits `igtf_payable` (2.2.04) instead of 2.2.02, every line on the center of that role. An `islr_withholding` remittance names `withholding_ids` too: every ISLR withholding named must be `certified` and of the month `period` (the month of its trigger date), and becomes `remitted`; from then on it is corrected with an adjustment instead of voided (409 remitted_withholding_requires_adjustment on its void), and the purchases invoice it was practised on cannot be cancelled. Its entry debits `islr_withholding_payable` (2.2.03) with the bolívars paid and, in each book, what the withholdings' determinations credited there, every line on the center of that role. A VAT withholding's id sent as `islr_withholding`, or an ISLR withholding's sent as `vat_withholding`, answers 422 remitted_withholding_not_found. The recording is written to the audit log as `backoffice.fiscal.withholding_remittance.recorded.v1`. `remitted_on` may not be after the company's today (422 cash_event_date_in_the_future) nor before the trigger date of a withholding it pays (422 remittance_dated_before_withholding) or the day a line's IGTF was perceived (422 remittance_dated_before_perception). The client generates the UUID `id`: resending it with the same terms — kind, period, day, trimmed bank reference, instrument and the same set of withholdings or lines in any order — answers 200 with the remittance as it stands, even if voided since; with other terms 409 withholding_remittance_id_conflict. A refusal of one withholding or line names it under `errors` as `withholding_ids.N` or `collection_method_line_ids.N`, N being its position in the request. Requires `backoffice.fiscal.remittances.manage`; an API key needs the `write` ability.", "operationId": "recordFiscalWithholdingRemittance", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "id", "kind", "period", "remitted_on", "bank_reference", "payment_instrument_id" ], "properties": { "id": { "description": "Generated by the client once per remittance (UUIDv7) and reused on a retry.", "type": "string", "format": "uuid", "example": "0199e0a0-0000-7000-8000-000000000025" }, "kind": { "description": "What it pays: VAT withholdings (`withholding_ids`), the IGTF perceived on collection method lines (`collection_method_line_ids`) or ISLR withholdings (`withholding_ids`).", "type": "string", "enum": [ "vat_withholding", "igtf_perceived", "islr_withholding" ] }, "period": { "description": "The period remitted, by kind: for `vat_withholding` and `igtf_perceived` the fortnight `YYYY-MM-1` (days 1 to 15) or `YYYY-MM-2` (16 to the month's end); for `islr_withholding` the month `YYYY-MM`.", "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])(-[12])?$", "example": "2026-09-1" }, "remitted_on": { "description": "The day it was paid; not after the company's today.", "type": "string", "format": "date", "example": "2026-09-24" }, "bank_reference": { "description": "The bank reference of the payment: one line of 1 to 120 characters once trimmed.", "type": "string", "example": "SIM-Q1-IVA-25", "maxLength": 120, "minLength": 1 }, "payment_instrument_id": { "description": "An active payment instrument of the company in bolívars (see `GET treasury/payment-instruments/lookup?currency=VES`).", "type": "string", "format": "uuid", "example": "0199e0a0-0000-7000-8000-0000000000b1" }, "withholding_ids": { "description": "Required when `kind` is `vat_withholding` or `islr_withholding`, prohibited otherwise: the certified VAT or ISLR withholdings, of that kind, of `period` it pays, each once.", "type": "array", "items": { "type": "string", "format": "uuid" }, "example": [ "0199d1a0-0000-7000-8000-000000000008", "0199d1a0-0000-7000-8000-000000000011" ], "maxItems": 500, "minItems": 1 }, "collection_method_line_ids": { "description": "Required when `kind` is `igtf_perceived`, prohibited otherwise: the collection method lines of `period` whose perceived IGTF it pays, each once (see `GET fiscal/igtf-perceived`).", "type": "array", "items": { "type": "string", "format": "uuid" }, "example": [ "0199e0a0-0000-7000-8000-0000000014a1" ], "maxItems": 500, "minItems": 1 } }, "type": "object" } } } }, "responses": { "201": { "description": "Remittance recorded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FiscalWithholdingRemittance" } } } }, "200": { "description": "The same request replayed: the remittance as it stands", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FiscalWithholdingRemittance" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "403": { "description": "Missing backoffice.fiscal.remittances.manage, or a read-only API key (api_key_write_ability_required)", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Forbidden" }, "status": { "type": "integer", "example": 403 }, "detail": { "type": "string", "example": "You do not have permission to access this resource." }, "error_code": { "type": "string", "nullable": true, "enum": [ "api_key_write_ability_required" ] } }, "type": "object" } } } }, "404": { "description": "company_not_found: the tenant company does not exist", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "detail": { "type": "string" }, "error_code": { "type": "string", "enum": [ "company_not_found" ] } }, "type": "object" } } } }, "409": { "description": "withholding_already_remitted: another remittance that stands already pays a VAT or ISLR withholding, named in `errors` as `withholding_ids.N` (a concurrent remittance caught by the store names none), with the detail «La retención de IVA ya está enterada.» or «La retención de ISLR ya está enterada.»; perceived_igtf_already_remitted: another remittance that stands already pays a line's perceived IGTF, named in `errors` as `collection_method_line_ids.N` (a concurrent remittance caught by the store names none); withholding_remittance_id_conflict: the id is known with other terms. Nothing is written", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "detail": { "type": "string", "example": "La retención de IVA ya está enterada." }, "error_code": { "type": "string", "enum": [ "withholding_already_remitted", "perceived_igtf_already_remitted", "withholding_remittance_id_conflict" ] }, "errors": { "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" } } } }, "422": { "description": "A malformed field, named in `errors`, or a business rule refused the remittance, also named in `errors`: remittance_period_mismatch and remitted_withholding_not_found (`withholding_ids.N`: a withholding of another fortnight, or for `islr_withholding` of another month, still determined, voided, unknown, of another company or of the other withholding kind), remittance_period_mismatch, remitted_igtf_line_not_found and perceived_igtf_not_valued_in_bolivares (`collection_method_line_ids.N`: a line of another fortnight, of a cancelled collection, that perceived no IGTF, unknown, of another company, or valued in a functional book that does not keep bolívars), remittance_dated_before_withholding, remittance_dated_before_perception and cash_event_date_in_the_future (`remitted_on`), remittance_instrument_not_found, remittance_instrument_inactive, remittance_instrument_treasury_account_inactive and remittance_instrument_not_in_bolivares (`payment_instrument_id`). When no official rate can value the remittance, the company cannot post to a role its entry needs (FISCAL_ACCOUNT_MISSING names `vat_withholding_payable`, `igtf_payable` or `islr_withholding_payable` by kind) or the period is closed, the body is instead `{error: accounting_configuration_incomplete, missing[]}` with no `error_code`. Nothing is written", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "description": "For remittance_period_mismatch, «…de la quincena YYYY-MM-N.» or «…del mes YYYY-MM.» by kind.", "type": "string", "example": "Solo se enteran retenciones certificadas de la quincena 2026-09-1." }, "error_code": { "type": "string", "nullable": true, "enum": [ "remittance_period_mismatch", "remitted_withholding_not_found", "remitted_igtf_line_not_found", "perceived_igtf_not_valued_in_bolivares", "remittance_dated_before_withholding", "remittance_dated_before_perception", "cash_event_date_in_the_future", "remittance_instrument_not_found", "remittance_instrument_inactive", "remittance_instrument_treasury_account_inactive", "remittance_instrument_not_in_bolivares", "invalid_remittance_bank_reference", "invalid_withholding_remittance_id", "invalid_islr_withholding_month", "unsupported_cash_event_currency" ] }, "errors": { "description": "The offending request fields, each with its messages.", "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "error": { "description": "Only on an accounting readiness gap, which carries `missing` instead of the fields above.", "type": "string", "enum": [ "accounting_configuration_incomplete" ] }, "missing": { "description": "Only on an accounting readiness gap: the official rate that cannot value the remittance, every posting account role its entry needs and the company cannot post to, or the closed period.", "type": "array", "items": { "required": [ "reason_code", "subject_type", "subject_id", "human_message", "details" ], "properties": { "reason_code": { "type": "string", "example": "OFFICIAL_RATE_NOT_AVAILABLE", "enum": [ "OFFICIAL_RATE_STALE", "OFFICIAL_RATE_NOT_AVAILABLE", "FISCAL_ACCOUNT_MISSING", "EXCHANGE_POSTING_ACCOUNT_MISSING", "ACCOUNTING_PERIOD_CLOSED" ] }, "subject_type": { "type": "string", "example": "payment_method" }, "subject_id": { "type": "string" }, "human_message": { "type": "string" }, "details": { "type": "array", "items": { "type": "string" } } }, "type": "object" } } }, "type": "object" } } } }, "500": { "description": "Internal server error, such as a settlement or an entry that would not balance (invalid_settlement, invalid_withholding_remittance, invalid_transaction_balance, empty_transaction_items), a stored perceived line without its value (invalid_perceived_igtf_line), a ledger write that failed (transaction_persistence_failed) or a Treasury Position with ledger lines without a side (treasury_position_has_unsided_ledger_lines); nothing is written", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Internal Server Error" }, "status": { "type": "integer", "example": 500 }, "detail": { "type": "string", "example": "An Unexpected Error Occurred" }, "error_code": { "type": "string", "nullable": true } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/fiscal/withholding-remittances/{id}/void": { "post": { "tags": [ "Backoffice - Fiscal Withholdings" ], "summary": "Void a withholding remittance", "description": "Voids a withholding remittance (MER-3111, glossary command VoidWithholdingRemittance), with a reason. In the same transaction: every VAT or ISLR withholding it paid is `certified` again and may be remitted anew (MER-3703), every collection method line an `igtf_perceived` remittance paid reads `pending_remittance` again and its collection may be cancelled (MER-3690), `withholding_remittance.voided` posts dated the company's today inverting every line of its `withholding_remittance.recorded` entry in both books, and the voiding is written to the audit log as `backoffice.fiscal.withholding_remittance.voided.v1` with who voided it and why. A voided remittance answers 409 withholding_remittance_already_voided and nothing is written. A blank reason, or one longer than 500 characters once trimmed, answers the validator's 422 with `errors.reason`. Requires `backoffice.fiscal.remittances.manage`; an API key needs the `write` ability.", "operationId": "voidFiscalWithholdingRemittance", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "The remittance id.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "reason" ], "properties": { "reason": { "description": "Why it is voided: 1 to 500 characters once trimmed; inner line breaks are kept.", "type": "string", "example": "Referencia bancaria equivocada; se registrará de nuevo.", "maxLength": 500, "minLength": 1 } }, "type": "object" } } } }, "responses": { "200": { "description": "Remittance voided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FiscalWithholdingRemittance" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "403": { "description": "Missing backoffice.fiscal.remittances.manage, or a read-only API key (api_key_write_ability_required)", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Forbidden" }, "status": { "type": "integer", "example": 403 }, "detail": { "type": "string", "example": "You do not have permission to access this resource." }, "error_code": { "type": "string", "nullable": true, "enum": [ "api_key_write_ability_required" ] } }, "type": "object" } } } }, "404": { "description": "withholding_remittance_not_found: the company keeps no remittance with this id, another company's included", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "detail": { "type": "string" }, "error_code": { "type": "string", "enum": [ "withholding_remittance_not_found", "company_not_found" ] } }, "type": "object" } } } }, "409": { "description": "withholding_remittance_already_voided: the remittance is already voided; nothing is written", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "detail": { "type": "string", "example": "El enteramiento ya está anulado." }, "error_code": { "type": "string", "enum": [ "withholding_remittance_already_voided" ] } }, "type": "object" } } } }, "422": { "description": "A blank or too long reason (`errors.reason`), or an id that is not a UUID (invalid_withholding_remittance_id); nothing is written", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string" }, "error_code": { "type": "string", "nullable": true, "enum": [ "invalid_withholding_remittance_id", "invalid_withholding_remittance_void_reason" ] }, "errors": { "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" } } } }, "500": { "description": "The voiding could not free its withholdings or invert the entry (withholding_remittance_posted_transaction_missing, transaction_already_reversed, invalid_withholding_remittance, invalid_vat_withholding, invalid_islr_withholding, invalid_transaction_balance, empty_transaction_items or transaction_persistence_failed); nothing is written", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Internal Server Error" }, "status": { "type": "integer", "example": 500 }, "detail": { "type": "string", "example": "An Unexpected Error Occurred" }, "error_code": { "type": "string", "nullable": true } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/fiscal/withholding-workpapers/{kind}/{period}": { "get": { "tags": [ "Backoffice - Fiscal - Withholding Workpapers" ], "summary": "Show the withholding workpaper of one remittance kind and period", "description": "Computes the Withholding Workpaper from live status aggregates: bolívares to certify, to remit and remitted for one `WithholdingRemittanceKind` and remittance period, with drill-down filters and the recorded remittances of the remitted bucket (MER-4148). Requires `backoffice.fiscal.withholdings.view`.", "operationId": "showWithholdingWorkpaper", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "kind", "in": "path", "description": "vat_withholding, islr_withholding or igtf_perceived", "required": true, "schema": { "type": "string", "example": "vat_withholding", "enum": [ "vat_withholding", "islr_withholding", "igtf_perceived" ] } }, { "name": "period", "in": "path", "description": "A fortnight YYYY-MM-1|2 for VAT and IGTF, or a month YYYY-MM for ISLR", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])(-[12])?$", "example": "2026-09-1" } } ], "responses": { "200": { "description": "The computed withholding workpaper", "content": { "application/json": { "schema": { "required": [ "kind", "period", "currency", "to_certify", "to_remit", "remitted" ], "properties": { "kind": { "type": "string", "example": "vat_withholding", "enum": [ "vat_withholding", "islr_withholding", "igtf_perceived" ] }, "period": { "type": "string", "example": "2026-09-1" }, "currency": { "type": "string", "example": "VES" }, "to_certify": { "description": "Null for igtf_perceived (no determined state); otherwise a bucket", "required": [ "amount", "count", "filter" ], "properties": { "amount": { "type": "string", "example": "0.00" }, "count": { "type": "integer", "example": 0 }, "filter": { "$ref": "#/components/schemas/WithholdingWorkpaperListFilter" } }, "type": "object", "nullable": true }, "to_remit": { "$ref": "#/components/schemas/WithholdingWorkpaperBucket" }, "remitted": { "$ref": "#/components/schemas/WithholdingWorkpaperRemittedBucket" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "403": { "description": "Missing backoffice.fiscal.withholdings.view", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Forbidden" }, "status": { "type": "integer", "example": 403 }, "detail": { "type": "string", "example": "You do not have permission to access this resource." } }, "type": "object" } } } }, "404": { "description": "The company does not exist (company_not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithholdingWorkpaperProblem" }, "example": { "title": "Not Found", "status": 404, "detail": "La empresa con el id … no existe", "error_code": "company_not_found", "errors": null } } } }, "422": { "description": "The kind or period is malformed (errors.kind / errors.period), or the period is the other type for the kind (remittance_period_type_mismatch with expected_period_type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithholdingWorkpaperProblem" }, "example": { "title": "Unprocessable Entity", "status": 422, "detail": "El tipo de enteramiento exige un período de tipo month, así que <2026-09-1> no le corresponde", "error_code": "remittance_period_type_mismatch", "errors": null, "expected_period_type": "month" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/getting-started": { "get": { "tags": [ "Backoffice - Getting Started" ], "summary": "Read the ten ordered company setup steps", "description": "Membership-only summary. Returns labels, routes and completion booleans, plus the number of Items missing a purchase or sales tax in the Item tax step label. No catalog records. Fiscal setup is required only when either book is in VES. The accounts step asks for an active Posting Account of every role but `non_deductible_vat`, which it asks for only while the company keeps an active Company Fiscal Profile and is not an ordinary VAT taxpayer in the Vigencia in force on its today (MER-5393).", "operationId": "getGettingStarted", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Ordered setup checklist", "content": { "application/json": { "schema": { "required": [ "steps" ], "properties": { "steps": { "type": "array", "items": { "required": [ "id", "group", "label", "done", "path" ], "properties": { "id": { "type": "string" }, "group": { "type": "string" }, "label": { "type": "string" }, "done": { "type": "boolean" }, "path": { "type": "string" } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Tenant membership or subscription access denied" }, "404": { "description": "Company not found" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/history": { "get": { "tags": [ "History" ], "summary": "Get history records", "operationId": "95a6918367db8c5a8d22d391e337223b", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "historiable_type", "in": "query", "description": "Type of entity to filter by. Required; must be a mapped document type.", "required": true, "schema": { "type": "string" } }, { "name": "historiable_id", "in": "query", "description": "ID of entity to filter by", "required": false, "schema": { "type": "string" } }, { "name": "user_id", "in": "query", "description": "User ID to filter by", "required": false, "schema": { "type": "string" } }, { "name": "date_from", "in": "query", "description": "Start date filter", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "date_to", "in": "query", "description": "End date filter", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "per_page", "in": "query", "description": "Number of items per page", "required": false, "schema": { "type": "integer", "default": 15 } }, { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer", "default": 1 } } ], "responses": { "200": { "description": "History records retrieved successfully", "content": { "application/json": { "schema": { "properties": { "items": { "type": "array", "items": { "properties": { "id": { "type": "string" }, "description": { "type": "string" }, "historiable_type": { "type": "string" }, "historiable_id": { "type": "string" }, "before": { "description": "Previous event data reconstructed by the document strategy. An absent previous state is serialized as an empty array.", "anyOf": [ { "type": "object", "additionalProperties": true }, { "type": "array", "items": {}, "maxItems": 0 } ] }, "after": { "description": "Immutable event data varies by document and event kind. Additional source, actor, code and cancellation facts may have null values. Provider mutation snapshots retain event_name and changed_fields. Dispatch events add responsible ID/name snapshots, line ID, exact expected quantity, change_source and triggered_by_user_id; absent legacy facts remain unknown. Entry events add responsible ID/name snapshots. Transformation responsible events add previous/new responsible id and name snapshots and actor_name. Client mutation snapshots retain event_name, event_id, occurred_on, actor_id and changed_fields with an explicit before; Adjustment responsible events add previous/new responsible id and name snapshots and actor_name; a cleared Responsable reads null and 'Sin responsable'. Adjustment header events may carry accounting_center_id. Item mutation snapshots retain event_name, event_id, occurred_on, actor_id and changed_fields with an explicit before; sale_price is null or {amount, currency}, barcode and sku are a string or null. Price list rows (price_lists) carry event_name, event_id, occurred_on, actor_id and changed_fields with an explicit before; entry rows add item {id, code, name}; an import summary row («Precios importados») carries import_id, original_filename, created_count, updated_count, unchanged_count, error_count and total_count with a null before. Collaboration retains its capability shape.", "properties": { "event_name": { "type": "string" }, "event_id": { "type": "string", "format": "uuid" }, "occurred_on": { "description": "Original event timestamp; never substitutes the persisted created_at", "type": "string" }, "actor_id": { "type": "string", "nullable": true }, "change_source": { "type": "string", "nullable": true, "enum": [ "manual", "origin_cancelled", "origin_credited" ] }, "triggered_by_user_id": { "type": "string", "nullable": true }, "inventory_dispatch_item_id": { "type": "string", "format": "uuid" }, "expected_quantity": { "type": "string", "nullable": true }, "responsible_user_id": { "type": "string", "nullable": true }, "responsible_user_name": { "type": "string", "nullable": true }, "previous_responsible_user_id": { "type": "string", "nullable": true }, "new_responsible_user_id": { "type": "string", "nullable": true }, "previous_responsible_user_name": { "type": "string", "nullable": true }, "new_responsible_user_name": { "type": "string", "nullable": true }, "changed_fields": { "type": "array", "items": { "type": "string" } } }, "type": "object", "additionalProperties": true }, "user_id": { "type": "string" }, "user_name": { "type": "string" }, "company_id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" } }, "total": { "type": "integer" }, "per_page": { "type": "integer" }, "current_page": { "type": "integer" } }, "type": "object" } } } }, "403": { "description": "Caller lacks the document view permission for historiable_type" }, "422": { "description": "Missing, empty, or unmapped historiable_type", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string" }, "error_code": { "type": "string", "example": "unknown_historiable_type" } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/adjustments/{id}/approve": { "post": { "tags": [ "Backoffice - Inventory Adjustments" ], "summary": "Approve an inventory adjustment", "operationId": "3651986e97a74c43e7f25cc7b617bff4", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Empty JSON object acknowledgement; refresh the record, its Activity and its entries", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdjustmentAcknowledgement" } } } }, "400": { "description": "Invalid adjustment approval. An already approved adjustment returns error_code adjustment_already_approved; a negative adjustment whose location lacks the stock returns error_code insufficient_stock.", "content": { "application/json": { "schema": { "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string", "example": "Bad Request" }, "status": { "type": "integer", "example": 400 }, "detail": { "type": "string" }, "error_code": { "type": "string", "example": "adjustment_already_approved", "nullable": true }, "errors": { "type": "object", "nullable": true } }, "type": "object" } } } }, "422": { "description": "The approval cannot be valued or posted and nothing is written. A company keeping different functional and reporting currencies needs the official rate of its approval day to value a positive line without a reporting unit price (OFFICIAL_RATE_NOT_AVAILABLE, details: pair and value date); the ledger may name other missing configuration.", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "enum": [ "accounting_configuration_incomplete" ] }, "missing": { "type": "array", "items": { "properties": { "reason_code": { "type": "string", "example": "OFFICIAL_RATE_NOT_AVAILABLE" }, "subject_type": { "type": "string", "example": "invoice" }, "subject_id": { "type": "string", "format": "uuid" }, "human_message": { "type": "string" }, "details": { "description": "For OFFICIAL_RATE_NOT_AVAILABLE: the currency pair and the value date it needs.", "type": "array", "items": { "type": "string" }, "example": [ "USD/VES", "2026-10-02" ] } }, "type": "object" } } }, "type": "object" } } } }, "403": { "description": "Unauthorized" }, "404": { "description": "HTTP 404; adjustment_not_found for a missing adjustment or one of another company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdjustmentProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/adjustments/{id}": { "get": { "tags": [ "Backoffice - Inventory Adjustments" ], "summary": "Get an inventory adjustment (Ajuste de inventario)", "description": "The record, in the list row's shape. Lines come in ascending id, in the item's base unit, with exact decimal strings; the valuation fields are null until approval.", "operationId": "06e2e69de6b69b02eba9fa5ebbea6727", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "Adjustment ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Adjustment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdjustmentResource" } } } }, "401": { "description": "HTTP 401", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdjustmentUnauthenticated" } } } }, "403": { "description": "HTTP 403; needs backoffice.inventory.adjustments.view", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdjustmentForbidden" } } } }, "404": { "description": "HTTP 404; adjustment_not_found for a missing adjustment or one of another company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdjustmentProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Backoffice - Inventory Adjustments" ], "summary": "Edit a pending inventory adjustment (Ajuste de inventario)", "description": "Replaces the reason, location, accounting center and lines of a pending adjustment. A responsibleUserId in the body is ignored; reassign through PUT /{id}/responsible. Concurrent pending edits are last-write-wins.", "operationId": "f436f1d9303c656233dfe292b2fbaa75", "parameters": [ { "name": "tenant", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "Adjustment ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "reason", "locationId", "accountingCenterId", "items" ], "properties": { "reason": { "type": "string", "example": "Conteo corregido", "maxLength": 255 }, "locationId": { "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440001" }, "accountingCenterId": { "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440002" }, "items": { "description": "Distinct line ids. Quantity, unitPrice and subTotal are decimal strings; the server also accepts JSON numbers.", "type": "array", "items": { "required": [ "id", "categoryId", "itemId", "quantity", "unitId", "unitPrice", "subTotal", "offsetAccountId", "assetAccountId" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440003" }, "categoryId": { "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440004" }, "itemId": { "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440005" }, "quantity": { "description": "Greater than zero, up to 11 integer digits and 4 decimals. A JSON number is also accepted.", "type": "string", "pattern": "^\\d{1,11}(\\.\\d{1,4})?$", "example": "1.5" }, "unitId": { "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440006" }, "unitPrice": { "description": "Up to 13 integer digits and 8 decimals (a negative line may send the item's average cost); stored with 2 decimals. A JSON number is also accepted.", "type": "string", "pattern": "^\\d{1,13}(\\.\\d{1,8})?$", "example": "25.50" }, "reportingUnitPrice": { "description": "Reporting-book unit cost of a positive line, in the line's unit, with up to 8 decimals (the inventory cost scale, so a pending line read back can be re-sent unchanged); when absent the approval values it from the official rate of the approval day. Ignored for negative lines, which relieve stock at each book's average, and when both books share a currency. The server also accepts a JSON number; the contract publishes the decimal string so the field stays nullable in generated clients.", "type": "string", "pattern": "^(?!0+(?:\\.0+)?$)\\d+(?:\\.\\d{1,8})?$", "example": "8.0000", "nullable": true }, "subTotal": { "description": "quantity x unitPrice rounded half-up to 2 decimals; a positive line posts this value on approval. A JSON number is also accepted.", "type": "string", "pattern": "^\\d{1,13}(\\.\\d{1,2})?$", "example": "38.25" }, "offsetAccountId": { "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440007" }, "assetAccountId": { "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440008" } }, "type": "object" }, "minItems": 1 } }, "type": "object" } } } }, "responses": { "200": { "description": "Empty JSON object acknowledgement; refetch the record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdjustmentAcknowledgement" } } } }, "401": { "description": "HTTP 401", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdjustmentUnauthenticated" } } } }, "403": { "description": "HTTP 403; needs backoffice.inventory.adjustments.update", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdjustmentForbidden" } } } }, "404": { "description": "HTTP 404; adjustment_not_found for a missing adjustment or one of another company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdjustmentProblem" } } } }, "409": { "description": "HTTP 409; adjustment_cannot_be_modified with adjustment_status when the adjustment is approved or rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdjustmentClosedProblem" } } } }, "422": { "description": "HTTP 422; validation with errors keyed like items.0.unitPrice, or invalid_item_unit_combination, invalid_adjustment_item_quantity, invalid_adjustment_item_unit_price, invalid_adjustment_item_reporting_unit_price, adjustment_must_have_at_least_one_item", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdjustmentProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/adjustments": { "get": { "tags": [ "Backoffice - Inventory Adjustments" ], "summary": "List inventory adjustments (Ajustes de inventario)", "description": "Values are ORed within a field and ANDed across fields. meta.counts drops only the status filter; meta.label_counts drops only label_ids. Unknown parameters are ignored. A search with no match is an empty page.", "operationId": "df19b326320a28d5925aea5bf74f5d1b", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "status[]", "in": "query", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "pending", "approved", "rejected" ] } } }, { "name": "status", "in": "query", "description": "Scalar alias of status[]; all or an empty value does not filter.", "schema": { "type": "string", "enum": [ "pending", "approved", "rejected", "all" ] } }, { "name": "type[]", "in": "query", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "positive", "negative" ] } } }, { "name": "type", "in": "query", "description": "Scalar alias of type[]; all or an empty value does not filter.", "schema": { "type": "string", "enum": [ "positive", "negative", "all" ] } }, { "name": "location_id[]", "in": "query", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" } } }, { "name": "location_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "locationId", "in": "query", "description": "Joins location_id; use location_id", "deprecated": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "responsible_user_id[]", "in": "query", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "pattern": "^(?:[1-9][0-9]{0,17}|[1-8][0-9]{18}|9[0-1][0-9]{17}|92[0-1][0-9]{16}|922[0-2][0-9]{15}|9223[0-2][0-9]{14}|92233[0-6][0-9]{13}|922337[0-1][0-9]{12}|92233720[0-2][0-9]{10}|922337203[0-5][0-9]{9}|9223372036[0-7][0-9]{8}|92233720368[0-4][0-9]{7}|922337203685[0-3][0-9]{6}|9223372036854[0-6][0-9]{5}|92233720368547[0-6][0-9]{4}|922337203685477[0-4][0-9]{3}|9223372036854775[0-7][0-9]{2}|922337203685477580[0-6]|9223372036854775807)$" } } }, { "name": "responsible_user_id", "in": "query", "schema": { "type": "string", "pattern": "^(?:[1-9][0-9]{0,17}|[1-8][0-9]{18}|9[0-1][0-9]{17}|92[0-1][0-9]{16}|922[0-2][0-9]{15}|9223[0-2][0-9]{14}|92233[0-6][0-9]{13}|922337[0-1][0-9]{12}|92233720[0-2][0-9]{10}|922337203[0-5][0-9]{9}|9223372036[0-7][0-9]{8}|92233720368[0-4][0-9]{7}|922337203685[0-3][0-9]{6}|9223372036854[0-6][0-9]{5}|92233720368547[0-6][0-9]{4}|922337203685477[0-4][0-9]{3}|9223372036854775[0-7][0-9]{2}|922337203685477580[0-6]|9223372036854775807)$" } }, { "name": "label_ids[]", "in": "query", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 20 } }, { "name": "label_ids", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "search", "in": "query", "description": "Matches the code or the reason", "schema": { "type": "string", "maxLength": 255 } }, { "name": "date_from", "in": "query", "description": "Inclusive UTC day of the creation", "schema": { "type": "string", "format": "date" } }, { "name": "date_to", "in": "query", "description": "Inclusive UTC day of the creation: the day itself counts. Must not be before date_from.", "schema": { "type": "string", "format": "date" } }, { "name": "sort_by", "in": "query", "schema": { "type": "string", "default": "code", "enum": [ "code", "created_at" ] } }, { "name": "sort_order", "in": "query", "description": "An id tie follows the same direction", "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } }, { "name": "group_by", "in": "query", "description": "Orders pending, approved, rejected before paginating", "schema": { "type": "string", "enum": [ "status" ] } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 10, "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdjustmentsPage" } } } }, "401": { "description": "HTTP 401", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdjustmentUnauthenticated" } } } }, "403": { "description": "HTTP 403; needs backoffice.inventory.adjustments.view", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdjustmentForbidden" } } } }, "422": { "description": "HTTP 422; errors names the parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdjustmentProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Inventory Adjustments" ], "summary": "Create an inventory adjustment (Ajuste de inventario)", "description": "Creates a pending adjustment with the client's id and answers that id; read the code from the record. Lines are converted to each item's base unit. A re-POST of an existing id answers 409 and changes nothing.", "operationId": "c8d3ad97d4943c14b352cb5bcabca134", "parameters": [ { "name": "tenant", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "id", "type", "reason", "locationId", "accountingCenterId", "items" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000" }, "type": { "type": "string", "example": "positive", "enum": [ "positive", "negative" ] }, "reason": { "type": "string", "example": "Donación recibida", "maxLength": 255, "minLength": 3 }, "locationId": { "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440001" }, "accountingCenterId": { "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440002" }, "responsibleUserId": { "description": "Optional Responsable: a user of the company, as a string; omit it or send null for none", "type": "string", "pattern": "^(?:[1-9][0-9]{0,17}|[1-8][0-9]{18}|9[0-1][0-9]{17}|92[0-1][0-9]{16}|922[0-2][0-9]{15}|9223[0-2][0-9]{14}|92233[0-6][0-9]{13}|922337[0-1][0-9]{12}|92233720[0-2][0-9]{10}|922337203[0-5][0-9]{9}|9223372036[0-7][0-9]{8}|92233720368[0-4][0-9]{7}|922337203685[0-3][0-9]{6}|9223372036854[0-6][0-9]{5}|92233720368547[0-6][0-9]{4}|922337203685477[0-4][0-9]{3}|9223372036854775[0-7][0-9]{2}|922337203685477580[0-6]|9223372036854775807)$", "example": "42", "nullable": true }, "items": { "description": "Distinct line ids. Quantity, unitPrice and subTotal are decimal strings; the server also accepts JSON numbers.", "type": "array", "items": { "required": [ "id", "categoryId", "itemId", "quantity", "unitId", "unitPrice", "subTotal", "offsetAccountId", "assetAccountId" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440003" }, "categoryId": { "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440004" }, "itemId": { "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440005" }, "quantity": { "description": "Greater than zero, up to 11 integer digits and 4 decimals. A JSON number is also accepted.", "type": "string", "pattern": "^\\d{1,11}(\\.\\d{1,4})?$", "example": "1.5" }, "unitId": { "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440006" }, "unitPrice": { "description": "Up to 13 integer digits and 8 decimals (a negative line may send the item's average cost); stored with 2 decimals. A JSON number is also accepted.", "type": "string", "pattern": "^\\d{1,13}(\\.\\d{1,8})?$", "example": "25.50" }, "reportingUnitPrice": { "description": "Reporting-book unit cost of a positive line, in the line's unit, with up to 8 decimals (the inventory cost scale, so a pending line read back can be re-sent unchanged); when absent the approval values it from the official rate of the approval day. Ignored for negative lines, which relieve stock at each book's average, and when both books share a currency. The server also accepts a JSON number; the contract publishes the decimal string so the field stays nullable in generated clients.", "type": "string", "pattern": "^(?!0+(?:\\.0+)?$)\\d+(?:\\.\\d{1,8})?$", "example": "8.0000", "nullable": true }, "subTotal": { "description": "quantity x unitPrice rounded half-up to 2 decimals; a positive line posts this value on approval. A JSON number is also accepted.", "type": "string", "pattern": "^\\d{1,13}(\\.\\d{1,2})?$", "example": "38.25" }, "offsetAccountId": { "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440007" }, "assetAccountId": { "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440008" } }, "type": "object" }, "minItems": 1 } }, "type": "object" } } } }, "responses": { "201": { "description": "Created; navigate to the record with the id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdjustmentCreated" } } } }, "401": { "description": "HTTP 401", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdjustmentUnauthenticated" } } } }, "403": { "description": "HTTP 403; needs backoffice.inventory.adjustments.create", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdjustmentForbidden" } } } }, "409": { "description": "HTTP 409; adjustment_already_exists for an id already in use", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdjustmentProblem" } } } }, "422": { "description": "HTTP 422; validation with errors keyed like items.0.unitPrice, or adjustment_responsible_user_not_in_company, invalid_item_unit_combination, invalid_adjustment_item_quantity, invalid_adjustment_item_unit_price, invalid_adjustment_item_reporting_unit_price, adjustment_must_have_at_least_one_item", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdjustmentProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/adjustments/{id}/reject": { "post": { "tags": [ "Backoffice - Inventory Adjustments" ], "summary": "Reject an inventory adjustment", "operationId": "cefa715c6933dabb4c501a0fb6a8ad70", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Empty JSON object acknowledgement, also when the adjustment was already rejected; refresh the record, its Activity and its entries", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdjustmentAcknowledgement" } } } }, "400": { "description": "Rejecting an approved adjustment reverts its stock movement; error_code insufficient_stock when the location no longer holds the stock a positive adjustment added", "content": { "application/json": { "schema": { "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string", "example": "Bad Request" }, "status": { "type": "integer", "example": 400 }, "detail": { "type": "string" }, "error_code": { "type": "string", "example": "insufficient_stock", "nullable": true }, "errors": { "type": "object", "nullable": true } }, "type": "object" } } } }, "422": { "description": "The rejection cannot be posted and nothing is written. For each valued line of an approved positive adjustment and in each book, the rejection takes the value the line froze while units stay held and what the Item carries once none do, never more than the book carries nor less than zero, and posts the difference to cost of sales. So a line with a difference on an Item with no cost of sales account answers ITEM_COGS_ACCOUNT_MISSING; the ledger may name other missing configuration.", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "enum": [ "accounting_configuration_incomplete" ] }, "missing": { "type": "array", "items": { "properties": { "reason_code": { "type": "string", "example": "ITEM_COGS_ACCOUNT_MISSING" }, "subject_type": { "type": "string", "example": "inventory_item" }, "subject_id": { "type": "string", "format": "uuid" }, "human_message": { "type": "string" }, "details": { "type": "array", "items": { "type": "string" } } }, "type": "object" } } }, "type": "object" } } } }, "403": { "description": "Unauthorized" }, "404": { "description": "HTTP 404; adjustment_not_found for a missing adjustment or one of another company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdjustmentProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/adjustments/{id}/responsible": { "put": { "tags": [ "Backoffice - Inventory Adjustments" ], "summary": "Reassign the Responsable of an inventory adjustment (Ajuste de inventario)", "description": "Only a pending adjustment takes a new Responsable or clears it with null; an unchanged value writes nothing. The change is recorded in the adjustment Activity.", "operationId": "e795a0d9e6336fc1cd0a1b974a8215c2", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "Adjustment ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdjustmentResponsibleRequest" } } } }, "responses": { "200": { "description": "Empty JSON object acknowledgement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdjustmentAcknowledgement" } } } }, "401": { "description": "HTTP 401", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdjustmentUnauthenticated" } } } }, "403": { "description": "HTTP 403; needs backoffice.inventory.adjustments.update", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdjustmentForbidden" } } } }, "404": { "description": "HTTP 404; adjustment_not_found for a missing adjustment or one of another company", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/AdjustmentProblem" }, { "$ref": "#/components/schemas/AdjustmentUnauthenticated" } ] } } } }, "409": { "description": "HTTP 409; adjustment_responsible_cannot_be_reassigned for an approved or rejected adjustment, even with the same value", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdjustmentProblem" } } } }, "422": { "description": "HTTP 422; validation, or adjustment_responsible_user_not_in_company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdjustmentProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/book-currencies": { "get": { "tags": [ "Backoffice - Inventory - Book Currencies" ], "summary": "Get the currencies of the company's books for inventory costs", "description": "The functional and reporting currencies Inventory keeps each Average Cost in. Requires backoffice.inventory.items.view, never backoffice.companies.view, so inventory document authors can label each book's costs.", "operationId": "getInventoryBookCurrencies", "parameters": [ { "name": "tenant", "in": "path", "description": "Company (tenant) ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Currencies of the company's functional and reporting books", "content": { "application/json": { "schema": { "required": [ "functional_currency", "reporting_currency" ], "properties": { "functional_currency": { "description": "Currency of the company's functional book", "type": "string", "example": "VES" }, "reporting_currency": { "description": "Currency of the company's reporting book", "type": "string", "example": "USD" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated (Laravel Sanctum)", "content": { "application/json": { "schema": { "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "403": { "description": "Forbidden, always answered by middleware: the can:backoffice.inventory.items.view gate adds a null error_code and errors; tenant membership adds a reason; company access and API-key guardrails send only title, status and detail", "content": { "application/json": { "schema": { "required": [ "title", "status", "detail" ], "properties": { "title": { "type": "string", "example": "Forbidden" }, "status": { "type": "integer", "example": 403 }, "detail": { "type": "string", "example": "You do not have permission to access this resource." }, "error_code": { "type": "string", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "reason": { "type": "string", "example": "DENIED_NO_MEMBERSHIP" } }, "type": "object" } } } }, "404": { "description": "Unknown tenant or API key bound to another company (middleware message), or company not found (controller Problem)", "content": { "application/json": { "schema": { "oneOf": [ { "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Recurso no encontrado" } }, "type": "object" }, { "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "detail": { "type": "string" }, "error_code": { "type": "string", "example": "company_not_found", "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true } }, "type": "object" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/pos/catalog/categories": { "get": { "tags": [ "Backoffice - Inventory - Counter Catalog" ], "summary": "List the counter catalog's categories", "description": "The company's active categories for the sale station's grid (MER-5156): a narrow read on the POS surface (ADR 0321), each with its id and name only. Sorted by name, then id; unpaged. A company without an active category answers an empty list. Requires backoffice.sales.counter-sales.sell; a POS session token reaches it, while inventory/categories/lookup stays off the POS surface.", "operationId": "973020cd499168eb4e6995387e96cc91", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The active categories", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CounterCatalogCategoryList" } } } }, "401": { "description": "Unauthenticated: the auth middleware answers before the controller", "content": { "application/json": { "schema": { "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "403": { "description": "Without backoffice.sales.counter-sales.sell (the Problem body, from the route's permission gate, error_code null), or a caller who does not belong to the company (the tenant middleware's body, which carries a reason when the user has no role there)", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/CounterCatalogProblem" }, { "required": [ "title", "status", "detail" ], "properties": { "title": { "type": "string", "example": "Forbidden" }, "status": { "type": "integer", "example": 403 }, "detail": { "type": "string", "example": "You do not have access to this tenant" }, "reason": { "type": "string" } }, "type": "object" } ] } } } }, "404": { "description": "The middleware's answer for a tenant the caller or the POS token does not reach", "content": { "application/json": { "schema": { "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Recurso no encontrado" } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/pos/catalog/items": { "get": { "tags": [ "Backoffice - Inventory - Counter Catalog" ], "summary": "Search or browse the counter catalog", "description": "The sale station's catalog (MER-5156): a narrow read on the POS surface (ADR 0321). With q, the cashier's item search, exact match first: barcode, then SKU, then code, and only then a paged text phase over Item and Modelo names, the query used whole (ADR 0273); category_id is then ignored, so a scan finds its Item whatever category the grid shows. Without q, or with a blank q, a page of the active catalog by name, of category_id when given, with each Modelo's active Variantes there grouped under it. Either way every Item carries exactly its identity, codes, category, base unit, Modelo and values, and the thumbnail of its primary image: never a price, a cost or a stock, which the Cotización POS gives. Blank query values count as absent. Requires backoffice.sales.counter-sales.sell; a POS session token reaches it, while inventory/items/search stays off the POS surface.", "operationId": "7eeb5a4804bd355c67731005e36ec7c4", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "q", "in": "query", "description": "Searches when present: used whole, never split by hyphens, spaces or anything else; only the surrounding whitespace is trimmed, and a blank or whitespace-only q counts as absent and browses (only a q the domain trim alone empties, such as one of control characters, answers 422). Exact barcode, then exact SKU (byte for byte), then code ignoring letter case, active Items only; otherwise names, ignoring letter case and accents.", "required": false, "schema": { "type": "string", "maxLength": 255 } }, { "name": "category_id", "in": "query", "description": "Browses only this category's active Items and Variantes; ignored with q. An unknown or another company's category answers empty lists.", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "description": "Page of the browse or of the text phase; ignored by exact matches.", "required": false, "schema": { "type": "integer", "default": 1, "maximum": 1000, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Bounds items and groups separately.", "required": false, "schema": { "type": "integer", "default": 24, "maximum": 48, "minimum": 1 } } ], "responses": { "200": { "description": "The exact match, a page of the text phase or of the browse, or none", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CounterCatalogItemPage" } } } }, "401": { "description": "Unauthenticated: the auth middleware answers before the controller", "content": { "application/json": { "schema": { "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "403": { "description": "Without backoffice.sales.counter-sales.sell (the Problem body, from the route's permission gate, error_code null), or a caller who does not belong to the company (the tenant middleware's body, which carries a reason when the user has no role there)", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/CounterCatalogProblem" }, { "required": [ "title", "status", "detail" ], "properties": { "title": { "type": "string", "example": "Forbidden" }, "status": { "type": "integer", "example": 403 }, "detail": { "type": "string", "example": "You do not have access to this tenant" }, "reason": { "type": "string" } }, "type": "object" } ] } } } }, "404": { "description": "The middleware's answer for a tenant the caller or the POS token does not reach", "content": { "application/json": { "schema": { "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Recurso no encontrado" } }, "type": "object" } } } }, "422": { "description": "Query validation, with errors by parameter (error_code null): q is longer than 255 characters or holds only characters the domain trim removes, category_id is not a UUID, page is outside 1 to 1000, or per_page is outside 1 to 48. Callers that bypass this validator get the domain's bounds as invalid_item_search, without errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CounterCatalogProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/dispatches/{id}/accounting-readiness": { "get": { "tags": [ "Backoffice - Inventory Dispatches" ], "summary": "Get accounting readiness for an inventory dispatch", "operationId": "3a2761e58a13ca0e576ae80d775420db", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Accounting readiness snapshot", "content": { "application/json": { "schema": { "properties": { "ready": { "type": "boolean" }, "missing": { "type": "array", "items": { "properties": { "reason_code": { "type": "string" }, "subject_type": { "type": "string" }, "subject_id": { "type": "string" }, "human_message": { "type": "string" }, "details": { "type": "array", "items": { "type": "string" } } }, "type": "object" } }, "warnings": { "$ref": "#/components/schemas/AccountingReadinessWarnings" } }, "type": "object" } } } }, "403": { "description": "Unauthorized" }, "404": { "description": "Inventory dispatch not found" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/dispatches/{id}/cancel": { "post": { "tags": [ "Backoffice - Inventory - Dispatches" ], "summary": "Post inventory dispatch contract", "operationId": "18792bfbb82acedfe831bda844c0876a", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryDispatchAcknowledgement" } } } }, "401": { "description": "HTTP 401", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryDispatchUnauthenticated" } } } }, "403": { "description": "HTTP 403", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryDispatchForbidden" } } } }, "404": { "description": "HTTP 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryDispatchProblem" } } } }, "400": { "description": "HTTP 400", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryDispatchProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/dispatches/{id}/close-short": { "post": { "tags": [ "Backoffice - Inventory - Dispatches" ], "summary": "Close a partial sales dispatch short", "description": "Closes a Partial sales dispatch short (ADR 0271): the quantities still pending will not ship. The dispatch freezes as `closed_short`, which is terminal: it accepts no more quantity and cannot be cancelled. Each line keeps its own status and its quantity dispatched, and its open Reserva is released with reason `closed_short`, lowering Reservado by the open remainder while Existencia stays as it is, in the same transaction. A Pending, Completed, Cancelled or already closed-short dispatch, or a transfer, answers 409 `inventory_dispatch_cannot_be_closed_short` and nothing changes. It takes no body; the response carries no entity, so the client re-reads the dispatch, the list and the history. Requires `backoffice.inventory.dispatches.cancel`.", "operationId": "closeInventoryDispatchShort", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "Inventory dispatch ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Dispatch closed short and its open reservations released", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "403": { "description": "The user lacks backoffice.inventory.dispatches.cancel", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Forbidden" }, "status": { "type": "integer", "example": 403 }, "detail": { "type": "string", "example": "You do not have permission to access this resource." }, "error_code": { "type": "string", "example": null, "nullable": true }, "errors": { "type": "object", "nullable": true } }, "type": "object" } } } }, "404": { "description": "inventory_dispatch_not_found, also for another company's dispatch", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "detail": { "type": "string", "example": "El despacho con el id 0199d3a4-7a52-7c8e-9e51-4c1f2a3b4c5d no existe" }, "error_code": { "type": "string", "enum": [ "inventory_dispatch_not_found" ] }, "errors": { "type": "object", "nullable": true } }, "type": "object" } } } }, "409": { "description": "Only a Partial sales dispatch closes short: the dispatch is Pending, Completed, Cancelled, already closed short, or a transfer. Nothing changes; `detail` says why in Spanish.", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "detail": { "type": "string", "example": "El despacho ID2600034 ya se despachó completo: no queda cantidad pendiente por cerrar." }, "error_code": { "type": "string", "enum": [ "inventory_dispatch_cannot_be_closed_short" ] }, "errors": { "type": "object", "nullable": true } }, "type": "object" } } } }, "500": { "description": "Reservado or a Reserva drifted from the registry while releasing (reported); the transaction rolls back and nothing changes", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Internal Server Error" }, "status": { "type": "integer", "example": 500 }, "detail": { "type": "string" }, "error_code": { "type": "string", "nullable": true, "enum": [ "reserved_quantity_cannot_go_negative", "reservation_cannot_be_released", "active_reservation_missing" ] }, "errors": { "type": "object", "nullable": true } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/dispatches/{id}/enhanced": { "get": { "tags": [ "Backoffice - Inventory - Dispatches" ], "summary": "Get inventory dispatch contract", "operationId": "84e8101f4089313a46154e8efb1f462a", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryDispatchEnhancedResource" } } } }, "401": { "description": "HTTP 401", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryDispatchUnauthenticated" } } } }, "403": { "description": "HTTP 403", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryDispatchForbidden" } } } }, "404": { "description": "HTTP 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryDispatchProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/dispatches/{id}": { "get": { "tags": [ "Backoffice - Inventory - Dispatches" ], "summary": "Get inventory dispatch contract", "operationId": "de0e86d5c0b97f9c81b607d0c93db558", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryDispatchResource" } } } }, "401": { "description": "HTTP 401", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryDispatchUnauthenticated" } } } }, "403": { "description": "HTTP 403", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryDispatchForbidden" } } } }, "404": { "description": "HTTP 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryDispatchProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Backoffice - Inventory - Dispatches" ], "summary": "Put inventory dispatch contract", "operationId": "c393e5d9163ca772c8f61b0aa2b8da01", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryDispatchQuantityRequest" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryDispatchAcknowledgement" } } } }, "401": { "description": "HTTP 401", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryDispatchUnauthenticated" } } } }, "403": { "description": "HTTP 403", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryDispatchForbidden" } } } }, "404": { "description": "HTTP 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryDispatchProblem" } } } }, "400": { "description": "HTTP 400", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/InventoryDispatchProblem" }, { "$ref": "#/components/schemas/InventoryDispatchStockProblem" } ] } } } }, "409": { "description": "Inventory dispatch cannot be updated: it is cancelled or closed short (inventory_dispatch_cannot_be_updated, before any stock moves), or the quantity dispatched of a sales-origin dispatch would decrease (inventory_dispatch_quantity_cannot_decrease)", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/InventoryDispatchProblem" }, { "$ref": "#/components/schemas/InventoryDispatchDecreaseProblem" } ] } } } }, "422": { "description": "Validation or accounting configuration error", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/InventoryDispatchProblem" }, { "$ref": "#/components/schemas/InventoryDispatchAccountingConfigurationError" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/dispatches/{id}/guide": { "put": { "tags": [ "Backoffice - Inventory - Dispatches" ], "summary": "Record the external dispatch guide reference", "operationId": "2d1ff1423db15a25bbe0391cabbb6820", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "guide_number", "guide_control" ], "properties": { "guide_number": { "type": "string", "nullable": true, "maxLength": 255 }, "guide_control": { "type": "string", "nullable": true, "maxLength": 255 } }, "type": "object" } } } }, "responses": { "200": { "description": "Reference saved" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "404": { "description": "Movement not found" }, "422": { "description": "Invalid reference" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/dispatches/{id}/responsible": { "put": { "tags": [ "Backoffice - Inventory - Dispatches" ], "summary": "Put inventory dispatch contract", "operationId": "e2513d4cae0aa6ed9d47832cda16eee5", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryDispatchResponsibleRequest" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryDispatchResponsibleAcknowledgement" } } } }, "401": { "description": "HTTP 401", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryDispatchUnauthenticated" } } } }, "403": { "description": "HTTP 403", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryDispatchForbidden" } } } }, "404": { "description": "HTTP 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryDispatchProblem" } } } }, "409": { "description": "HTTP 409", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryDispatchProblem" } } } }, "422": { "description": "HTTP 422", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryDispatchProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/dispatches/{id}/revert": { "post": { "tags": [ "Backoffice - Inventory - Dispatches" ], "summary": "Change a sales dispatch back to Pending", "description": "Changes a Partial or Completed sales dispatch back to Pending («Cambiar a Pendiente», ADR 0140). Every quantity dispatched returns to 0 and each line forgets its frozen cost of sales. Existencia and Stock total come back per location and on the Item by quantity only; `average_cost` does not change. One `inventory_dispatch.reverted` entry, dated the company's local today, inverts in both books exactly the `inventory_dispatch.dispatched` entries posted since the last revert (none when nothing was posted). Each line's consumed Reserva takes back what the line gave back and Reservado rises by the same amount, so Disponible does not move (ADR 0319). The history records one quantity row per line and the status change. Everything happens in one transaction. Afterwards the invoice or order can be cancelled. A sales dispatch does not go back to Pending while a live approved Unit Return credits units of its sale (MER-2942). A transfer, a cancelled or closed-short dispatch, the dispatch of a cancelled invoice or order, or the dispatch of a Venta de mostrador's invoice (`sold_at_the_counter` on the enhanced detail; it goes back to Pending only by voiding the sale at the till, MER-4978) answers 409 `inventory_dispatch_cannot_be_reverted` and nothing changes. These refusals come first, so they reach a dispatch that is already Pending. Any other Pending dispatch answers 200 and writes nothing. It takes no body; the response carries no entity, so the client re-reads the dispatch, its history, its accounting entries and the lists. Requires `backoffice.inventory.dispatches.update_quantity`.", "operationId": "revertInventoryDispatch", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "Inventory dispatch ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The dispatch is Pending: this call reverted it, or it already was", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "403": { "description": "The user lacks backoffice.inventory.dispatches.update_quantity", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Forbidden" }, "status": { "type": "integer", "example": 403 }, "detail": { "type": "string", "example": "You do not have permission to access this resource." }, "error_code": { "type": "string", "example": null, "nullable": true }, "errors": { "type": "object", "nullable": true } }, "type": "object" } } } }, "404": { "description": "inventory_dispatch_not_found, also for another company's dispatch", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "detail": { "type": "string", "example": "El despacho con el id 0199d3a4-7a52-7c8e-9e51-4c1f2a3b4c5d no existe" }, "error_code": { "type": "string", "enum": [ "inventory_dispatch_not_found" ] }, "errors": { "type": "object", "nullable": true } }, "type": "object" } } } }, "409": { "description": "The dispatch is a transfer, is cancelled or closed short, belongs to a cancelled invoice or order, has a live approved Unit Return crediting units of its sale, or belongs to a charged Venta de mostrador's invoice («La factura {code} es de una venta de mostrador: se anula desde la caja. Su despacho {code} no se puede cambiar a Pendiente por separado.»). This holds for a dispatch that is already Pending too. Nothing changes; `detail` says why in Spanish.", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "detail": { "type": "string", "example": "El despacho ID2600034 está cancelado y no se puede cambiar a Pendiente." }, "error_code": { "type": "string", "enum": [ "inventory_dispatch_cannot_be_reverted" ] }, "errors": { "type": "object", "nullable": true } }, "type": "object" } } } }, "422": { "description": "The ledger refused the mirror entry: accounting configuration is incomplete for it, or the accounting period of today is closed. This body is not a Problem: it has `error` and `missing`, and no `detail`. Everything rolls back.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryDispatchAccountingConfigurationError" } } } }, "500": { "description": "Stored data drifted from what the revert expects (reported); the transaction rolls back and nothing changes. `error_code` is null for a corrupt posted journal line or any unexpected failure.", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Internal Server Error" }, "status": { "type": "integer", "example": 500 }, "detail": { "type": "string" }, "error_code": { "type": "string", "nullable": true, "enum": [ "inventory_dispatch_origin_document_missing", "reservation_cannot_be_restored", "restorable_reservation_missing", "transaction_persistence_failed" ] }, "errors": { "type": "object", "nullable": true } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/dispatches/enhanced": { "get": { "tags": [ "Backoffice - Inventory - Dispatches" ], "summary": "Get inventory dispatch contract", "operationId": "0dd25151cd0a3439f5eb6575f82479b2", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "status[]", "in": "query", "description": "A status set by hand (cancelled, closed_short) goes ahead of the one calculated from the lines, so partial excludes a dispatch closed short.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "pending", "partial", "completed", "cancelled", "closed_short" ] } } }, { "name": "status", "in": "query", "description": "A status set by hand (cancelled, closed_short) goes ahead of the one calculated from the lines, so partial excludes a dispatch closed short.", "schema": { "type": "string", "enum": [ "pending", "partial", "completed", "cancelled", "closed_short", "all" ] } }, { "name": "origin_type[]", "in": "query", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "sales_order", "sales_invoice", "inventory_transfer" ] } } }, { "name": "origin_type", "in": "query", "schema": { "type": "string", "enum": [ "sales_order", "sales_invoice", "inventory_transfer" ] } }, { "name": "responsible_user_id[]", "in": "query", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "pattern": "^(?:[1-9][0-9]{0,17}|[1-8][0-9]{18}|9[0-1][0-9]{17}|92[0-1][0-9]{16}|922[0-2][0-9]{15}|9223[0-2][0-9]{14}|92233[0-6][0-9]{13}|922337[0-1][0-9]{12}|92233720[0-2][0-9]{10}|922337203[0-5][0-9]{9}|9223372036[0-7][0-9]{8}|92233720368[0-4][0-9]{7}|922337203685[0-3][0-9]{6}|9223372036854[0-6][0-9]{5}|92233720368547[0-6][0-9]{4}|922337203685477[0-4][0-9]{3}|9223372036854775[0-7][0-9]{2}|922337203685477580[0-6]|9223372036854775807)$" } } }, { "name": "responsible_user_id", "in": "query", "schema": { "type": "string", "pattern": "^(?:[1-9][0-9]{0,17}|[1-8][0-9]{18}|9[0-1][0-9]{17}|92[0-1][0-9]{16}|922[0-2][0-9]{15}|9223[0-2][0-9]{14}|92233[0-6][0-9]{13}|922337[0-1][0-9]{12}|92233720[0-2][0-9]{10}|922337203[0-5][0-9]{9}|9223372036[0-7][0-9]{8}|92233720368[0-4][0-9]{7}|922337203685[0-3][0-9]{6}|9223372036854[0-6][0-9]{5}|92233720368547[0-6][0-9]{4}|922337203685477[0-4][0-9]{3}|9223372036854775[0-7][0-9]{2}|922337203685477580[0-6]|9223372036854775807)$" } }, { "name": "label_ids[]", "in": "query", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 20 } }, { "name": "label_ids", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "search", "in": "query", "schema": { "type": "string", "maxLength": 255 } }, { "name": "date_from", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "date_to", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "sort_by", "in": "query", "schema": { "type": "string", "enum": [ "code", "date" ] } }, { "name": "sort_order", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "group_by", "in": "query", "schema": { "type": "string", "enum": [ "status" ] } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 15, "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryDispatchesPage" } } } }, "401": { "description": "HTTP 401", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryDispatchUnauthenticated" } } } }, "403": { "description": "HTTP 403", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryDispatchForbidden" } } } }, "404": { "description": "HTTP 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryDispatchProblem" } } } }, "422": { "description": "HTTP 422", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryDispatchProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/dispatches": { "get": { "tags": [ "Backoffice - Inventory - Dispatches" ], "summary": "Search inventory dispatches", "description": "Returns a paginated list of inventory dispatches with optional filtering by code, origin and date range. It does not filter by status; GET inventory/dispatches/enhanced does.", "operationId": "7980b5dc98d2724b7c9fa1fa8c89e2f2", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant ID", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "Page number for pagination", "required": false, "schema": { "type": "integer", "example": 1, "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Number of items per page", "required": false, "schema": { "type": "integer", "example": 15, "default": 15, "maximum": 100, "minimum": 1 } }, { "name": "code", "in": "query", "description": "Part of the dispatch code", "required": false, "schema": { "type": "string", "example": "ID2400001" } }, { "name": "origin_type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "sales_order", "sales_invoice", "inventory_transfer" ] } }, { "name": "origin_id", "in": "query", "description": "The id of the origin document", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "date_from", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "date_to", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "sort_by", "in": "query", "description": "Any column of backoffice__inventory_dispatches, bare or prefixed with the table name and a dot. Without it the list orders by code descending. An empty value counts as absent. Any other value answers 422 invalid_list_sort.", "required": false, "schema": { "type": "string" } }, { "name": "sort_order", "in": "query", "description": "Checked even without sort_by, but it only orders a sort_by that is sent; a sort_by without it reads descending. Read ignoring case and surrounding spaces. An empty value counts as absent. Any other value answers 422 invalid_list_sort.", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "properties": { "dispatches": { "type": "array", "items": { "type": "object" } }, "total": { "type": "integer" }, "per_page": { "type": "integer" }, "current_page": { "type": "integer" } }, "type": "object" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "422": { "description": "invalid_list_sort: an unknown sort_by or a sort_order other than asc/desc; errors names the parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidListSortProblem" } } } }, "500": { "description": "Internal server error" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/entries/enhanced": { "get": { "tags": [ "Backoffice - Inventory - Entries" ], "summary": "List inventory entries with calculated status, origin facts and facets", "description": "Values are ORed within a filter and ANDed between filters; an empty filter does not filter. Each meta facet applies every filter except its own. An invalid value answers 422 instead of falling back.", "operationId": "9a5452095631514ae0a6ebed44a0fbd2", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "status[]", "in": "query", "description": "A cancelled (frozen) entry reads cancelled, and a Return Entry closed short reads closed_short (R6, ADR 0379), ahead of the status its lines give.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "pending", "partial", "completed", "closed_short", "cancelled" ] } } }, { "name": "status", "in": "query", "description": "Scalar alias of status[]; all does not filter.", "schema": { "type": "string", "enum": [ "pending", "partial", "completed", "closed_short", "cancelled", "all" ] } }, { "name": "origin_type[]", "in": "query", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "purchase_order", "inventory_transfer", "transformation", "sales_credit_note" ] } } }, { "name": "origin_type", "in": "query", "schema": { "type": "string", "enum": [ "purchase_order", "inventory_transfer", "transformation", "sales_credit_note" ] } }, { "name": "responsible_user_id[]", "in": "query", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "pattern": "^(?:[1-9][0-9]{0,17}|[1-8][0-9]{18}|9[0-1][0-9]{17}|92[0-1][0-9]{16}|922[0-2][0-9]{15}|9223[0-2][0-9]{14}|92233[0-6][0-9]{13}|922337[0-1][0-9]{12}|92233720[0-2][0-9]{10}|922337203[0-5][0-9]{9}|9223372036[0-7][0-9]{8}|92233720368[0-4][0-9]{7}|922337203685[0-3][0-9]{6}|9223372036854[0-6][0-9]{5}|92233720368547[0-6][0-9]{4}|922337203685477[0-4][0-9]{3}|9223372036854775[0-7][0-9]{2}|922337203685477580[0-6]|9223372036854775807)$" } } }, { "name": "responsible_user_id", "in": "query", "schema": { "type": "string", "pattern": "^(?:[1-9][0-9]{0,17}|[1-8][0-9]{18}|9[0-1][0-9]{17}|92[0-1][0-9]{16}|922[0-2][0-9]{15}|9223[0-2][0-9]{14}|92233[0-6][0-9]{13}|922337[0-1][0-9]{12}|92233720[0-2][0-9]{10}|922337203[0-5][0-9]{9}|9223372036[0-7][0-9]{8}|92233720368[0-4][0-9]{7}|922337203685[0-3][0-9]{6}|9223372036854[0-6][0-9]{5}|92233720368547[0-6][0-9]{4}|922337203685477[0-4][0-9]{3}|9223372036854775[0-7][0-9]{2}|922337203685477580[0-6]|9223372036854775807)$" } }, { "name": "label_ids[]", "in": "query", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 20 } }, { "name": "label_ids", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "search", "in": "query", "description": "Matches the entry code and the purchase order, transfer or transformation code or provider name", "schema": { "type": "string", "maxLength": 255 } }, { "name": "date_from", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "date_to", "in": "query", "description": "Inclusive: the whole day counts. Must not be before date_from.", "schema": { "type": "string", "format": "date" } }, { "name": "sort_by", "in": "query", "schema": { "type": "string", "default": "code", "enum": [ "code", "date" ] } }, { "name": "sort_order", "in": "query", "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } }, { "name": "group_by", "in": "query", "description": "Orders pending, partial, completed, closed_short, cancelled before paginating", "schema": { "type": "string", "enum": [ "status" ] } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 10, "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryEntriesPage" } } } }, "401": { "description": "HTTP 401", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryEntryUnauthenticated" } } } }, "403": { "description": "HTTP 403", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryEntryForbidden" } } } }, "422": { "description": "HTTP 422", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryEntryProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/entries": { "get": { "tags": [ "Backoffice - Inventory - Entries" ], "summary": "Search inventory entries", "operationId": "02c388349f24b28fbbe467e86bcf11a1", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 15, "maximum": 100, "minimum": 1 } }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "origin_type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "purchase_order", "inventory_transfer", "transformation", "sales_credit_note" ] } }, { "name": "date_from", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "date_to", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "sort_by", "in": "query", "description": "Any column of backoffice__inventory__entries, bare or prefixed with the table name and a dot. Without it the list orders by code descending. An empty value counts as absent. Any other value answers 422 invalid_list_sort.", "required": false, "schema": { "type": "string" } }, { "name": "sort_order", "in": "query", "description": "Checked even without sort_by, but it only orders a sort_by that is sent; a sort_by without it reads descending. Read ignoring case and surrounding spaces. An empty value counts as absent. Any other value answers 422 invalid_list_sort.", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Inventory entries retrieved successfully", "content": { "application/json": { "schema": { "properties": { "entries": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "origin_type": { "type": "string" }, "origin_id": { "type": "string", "format": "uuid" }, "date": { "type": "string", "format": "date-time" }, "company_id": { "type": "string", "format": "uuid" } }, "type": "object" } }, "total": { "type": "integer" }, "per_page": { "type": "integer" }, "page": { "type": "integer" } }, "type": "object" } } } }, "403": { "description": "Unauthorized" }, "422": { "description": "invalid_list_sort: an unknown sort_by or a sort_order other than asc/desc; errors names the parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidListSortProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/entries/{id}/accounting-readiness": { "get": { "tags": [ "Backoffice - Inventory Entries" ], "summary": "Get accounting readiness for an inventory entry", "operationId": "37d72e6447f5d770ce901cda6da82d42", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Accounting readiness snapshot", "content": { "application/json": { "schema": { "properties": { "ready": { "type": "boolean" }, "missing": { "type": "array", "items": { "properties": { "reason_code": { "type": "string" }, "subject_type": { "type": "string" }, "subject_id": { "type": "string" }, "human_message": { "type": "string" }, "details": { "type": "array", "items": { "type": "string" } } }, "type": "object" } }, "warnings": { "$ref": "#/components/schemas/AccountingReadinessWarnings" } }, "type": "object" } } } }, "403": { "description": "Unauthorized" }, "404": { "description": "Inventory entry not found" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/entries/{id}/close-short": { "post": { "tags": [ "Backoffice - Inventory - Entries" ], "summary": "Close a Return Entry short", "description": "Closes a Return Entry (origin `sales_credit_note`) short (R6, ADR 0379). A Return Entry that is pending or partial can be closed short. What was not received stays out, nothing posts, its cost stays in cost of sales, and the note's fiscal effect stands. The entry freezes as `closed_short`, which is terminal: a later receipt answers 409 `inventory_entry_cannot_be_received`. Its lines keep their units and frozen cost, so a later note on the same dispatch line cannot take them again; each line reads `quantity_not_received`. Damaged goods that came back are received and then written off by an ordinary negative Inventory Adjustment, at the Item's average. Another origin, or an entry already completed, cancelled or closed short, answers 409 `inventory_entry_cannot_be_closed_short` and nothing changes. It takes no body and locks only the entry row and its lines; the response carries no entity, so the client re-reads the entry, the list and the history. Requires `backoffice.inventory.entries.update_quantity`.", "operationId": "closeInventoryEntryShort", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "Inventory entry ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Return Entry closed short", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryEntryAcknowledgement" } } } }, "401": { "description": "HTTP 401", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryEntryUnauthenticated" } } } }, "403": { "description": "HTTP 403; needs backoffice.inventory.entries.update_quantity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryEntryForbidden" } } } }, "404": { "description": "HTTP 404; inventory_entry_not_found, also for an entry of another company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryEntryProblem" } } } }, "409": { "description": "HTTP 409; inventory_entry_cannot_be_closed_short: the entry is not a Return Entry, or it is completed, cancelled or already closed short. Nothing changes; `detail` says why in Spanish.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryEntryProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/entries/{id}/enhanced": { "get": { "tags": [ "Backoffice - Inventory - Entries" ], "summary": "Get an inventory entry record with line names, origin facts, Responsable and labels", "operationId": "cae43427ba8a60b06bf83aef014b5f33", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryEntryEnhancedResource" } } } }, "401": { "description": "HTTP 401", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryEntryUnauthenticated" } } } }, "403": { "description": "HTTP 403", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryEntryForbidden" } } } }, "404": { "description": "HTTP 404; a missing entry or one of another company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryEntryProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/entries/{id}": { "get": { "tags": [ "Backoffice - Inventory - Entries" ], "summary": "Get an inventory entry by ID", "operationId": "aad58fe14fcbc72edb58e12349d7b776", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryEntryResource" } } } }, "401": { "description": "HTTP 401", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryEntryUnauthenticated" } } } }, "403": { "description": "HTTP 403", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryEntryForbidden" } } } }, "404": { "description": "HTTP 404; a missing entry or one of another company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryEntryProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Backoffice - Inventory - Entries" ], "summary": "Receive quantities on inventory entry lines", "description": "Each quantity is the line's cumulative quantity received. A refused quantity answers 422 and marks it under the field it was sent under: errors[inventory_entry_item_quantities.], or errors[item_quantities.] on the legacy map; a cancelled (frozen) entry answers 409 before anything is locked or valued. A purchase-order receipt is valued at the official rate of the company's receipt day; without one it answers 422 OFFICIAL_RATE_NOT_AVAILABLE with the pair and the value date it needs, and nothing is written. A line that moves without naming its purchase-order line has no cost to freeze: it answers 422 inventory_entry_line_not_valued, and nothing is written. On a Return Entry (origin `sales_credit_note`), stock, Average Cost and Carrying Value move when someone receives the line. A receipt values its units at the line's frozen cost, rounded on the cumulative quantity, so the line's last unit takes what is left. It posts `inventory_entry.return_received` on the company's today: debit the Item's inventory account, credit the Item's cost of sales account, in both books. It needs no rate (MER-2942).", "operationId": "91d9a24a62083ad5734164740b13b30c", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryEntryQuantityRequest" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryEntryAcknowledgement" } } } }, "401": { "description": "HTTP 401", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryEntryUnauthenticated" } } } }, "403": { "description": "HTTP 403; needs backoffice.inventory.entries.update_quantity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryEntryForbidden" } } } }, "404": { "description": "HTTP 404; a missing entry or line, or an entry of another company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryEntryProblem" } } } }, "409": { "description": "HTTP 409; inventory_entry_cannot_be_received, or inventory_entry_receipt_raced when another receipt of the same purchase-order entry was saved at the same time (nothing was written; send it again)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryEntryProblem" } } } }, "422": { "description": "HTTP 422; validation, a refused quantity (invalid_quantity_update) or incomplete accounting configuration", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/InventoryEntryProblem" }, { "$ref": "#/components/schemas/InventoryEntryQuantityProblem" }, { "$ref": "#/components/schemas/InventoryEntryAccountingConfigurationError" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/entries/{id}/responsible": { "put": { "tags": [ "Backoffice - Inventory - Entries" ], "summary": "Reassign the Responsable of an inventory entry", "description": "Only a pending or partial entry takes a new Responsable; an unchanged value writes nothing. The change is recorded in the entry's Activity.", "operationId": "081a79622c4010a0defd633b4472ae2d", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryEntryResponsibleRequest" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryEntryAcknowledgement" } } } }, "401": { "description": "HTTP 401", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryEntryUnauthenticated" } } } }, "403": { "description": "HTTP 403; needs backoffice.inventory.entries.update_quantity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryEntryForbidden" } } } }, "404": { "description": "HTTP 404; inventory_entry_not_found for a missing entry or one of another company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryEntryProblem" } } } }, "409": { "description": "HTTP 409; inventory_entry_responsible_cannot_be_reassigned for a completed, cancelled or closed-short entry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryEntryProblem" } } } }, "422": { "description": "HTTP 422; validation or inventory_entry_responsible_user_not_in_company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryEntryProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/categories/lookup": { "get": { "tags": [ "Backoffice - Inventory - Item Category Lookups" ], "summary": "Lookup Item Categories for tenant forms", "operationId": "b60ef899aa02498ae74ab5939fc8b1ec", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "active", "inactive" ] } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 200, "minimum": 1 } } ], "responses": { "200": { "description": "Minimal Item Category projection", "content": { "application/json": { "schema": { "properties": { "items": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "inactive" ] } }, "type": "object" } }, "total": { "type": "integer" }, "per_page": { "type": "integer" }, "current_page": { "type": "integer" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Not a member of this tenant" }, "404": { "description": "Tenant not found" }, "422": { "description": "Invalid status filter" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/items/{itemId}/images/{imageId}": { "delete": { "tags": [ "Backoffice - Inventory Items" ], "summary": "Delete an Item image", "operationId": "72810b76140f63e3b15b440c353b999b", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "itemId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "imageId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Image deleted", "content": { "application/json": { "schema": { "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Image deleted successfully" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemError" } } } }, "403": { "description": "Forbidden or tenant access refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemError" } } } }, "404": { "description": "Tenant-scoped resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemError" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/item-images/{id}": { "get": { "tags": [ "Backoffice - Inventory Items" ], "summary": "Read an Item image", "operationId": "800aed2a5bfae9e2d9f1b39541b9b84a", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Tenant-scoped image", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemImage" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemError" } } } }, "403": { "description": "Forbidden or tenant access refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemError" } } } }, "404": { "description": "Tenant-scoped resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemError" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Backoffice - Inventory Items" ], "summary": "Delete an Item image through the legacy route", "operationId": "08f2f13780b6b4238356cf070121f25a", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Image deleted", "content": { "application/json": { "schema": { "required": [ "message" ], "properties": { "message": { "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemError" } } } }, "403": { "description": "Forbidden or tenant access refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemError" } } } }, "404": { "description": "Tenant-scoped resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemError" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/items/{itemId}/images/{imageId}/primary": { "put": { "tags": [ "Backoffice - Inventory Items" ], "summary": "Set an Item image as primary", "operationId": "79dfe87d1cee81435ba1a3c65708a6da", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "itemId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "imageId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Primary image changed or already primary", "content": { "application/json": { "schema": { "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Primary image updated successfully" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemError" } } } }, "403": { "description": "Forbidden or tenant access refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemError" } } } }, "404": { "description": "Tenant-scoped resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemError" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/items/{itemId}/images": { "get": { "tags": [ "Backoffice - Inventory Items" ], "summary": "List Item images", "operationId": "823f2b672412b8ca0864ac85b0eafe95", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "itemId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 10, "maximum": 50, "minimum": 1 } } ], "responses": { "200": { "description": "Image page", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemImagePage" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemError" } } } }, "403": { "description": "Forbidden or tenant access refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemError" } } } }, "422": { "description": "Existing image paging validation failure", "content": { "application/json": { "schema": { "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422, "enum": [ 422 ] }, "detail": { "type": "string", "example": "The given data was invalid." }, "error_code": { "description": "Null for request validation.", "type": "string", "example": null, "nullable": true }, "errors": { "description": "Field-keyed validation messages.", "type": "object", "example": { "page": [ "The page must be at least 1." ] }, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Inventory Items" ], "summary": "Upload an Item image", "description": "Requires Item UPDATE; uses route tenant. No processing-status endpoint exists.", "operationId": "3dc1c33533fa23e45ed10915737f31ed", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "itemId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "image" ], "properties": { "image": { "description": "jpeg/jpg/png/webp/gif; maximum 10 MiB; an image larger than 4000x4000 is scaled down to fit, keeping its proportions", "type": "string", "format": "binary" }, "alt_text": { "type": "string", "nullable": true, "maxLength": 255 }, "is_primary": { "type": "boolean", "default": false } }, "type": "object" } } } }, "responses": { "201": { "description": "Uploaded image; actual response has no original_url", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemImageUpload" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemError" } } } }, "403": { "description": "Forbidden or tenant access refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemError" } } } }, "400": { "description": "Invalid image, missing Item or maximum ten images exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemError" } } } }, "422": { "description": "Upload field validation failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemError" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/items/{itemId}/locations": { "get": { "tags": [ "Backoffice - Inventory Item Locations" ], "summary": "Get item locations for a specific item", "operationId": "c85011746f3b1dc3f01430114b68c586", "parameters": [ { "name": "tenant", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string" } }, { "name": "itemId", "in": "path", "description": "Item identifier", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "Page number. The response echoes the page served as `currentPage`.", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Items per page. The response echoes it as `per_page`.", "required": false, "schema": { "type": "integer", "default": 15, "maximum": 100, "minimum": 1 } }, { "name": "locationId", "in": "query", "description": "Location filter", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of item locations", "content": { "application/json": { "schema": { "required": [ "data", "total", "per_page", "currentPage" ], "properties": { "data": { "type": "array", "items": { "required": [ "id", "item_id", "location_id", "location_name", "available_quantity", "reserved_quantity", "sellable_quantity", "total_stock", "company_id" ], "properties": { "id": { "type": "string" }, "item_id": { "type": "string" }, "location_id": { "type": "string" }, "location_name": { "type": "string" }, "available_quantity": { "description": "Existencia: on-hand quantity at this location", "type": "string", "example": "10.0000" }, "reserved_quantity": { "description": "Cantidad reservada held by open reservations at this location (ADR 0270)", "type": "string", "example": "4.0000" }, "sellable_quantity": { "description": "Disponible: available_quantity minus reserved_quantity; negative means a shortage", "type": "string", "example": "6.0000" }, "total_stock": { "type": "string", "example": "10.0000" }, "pending_dispatch_quantity": { "description": "Pending sales dispatches in base units; cancelled and closed dispatches excluded", "type": "string", "example": "2.0000" }, "pending_receipt_quantity": { "description": "Approved purchase quantities still to receive in base units", "type": "string", "example": "5.0000" }, "in_transfer": { "description": "In-transit base quantity assigned to this destination", "type": "string", "example": "3.0000" }, "company_id": { "type": "string" } }, "type": "object" } }, "total": { "type": "integer" }, "per_page": { "description": "The page size served, echoing the `per_page` query", "type": "integer" }, "currentPage": { "description": "The page served, echoing the `page` query; 1 when it is absent", "type": "integer" } }, "type": "object" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemError" } } } }, "422": { "description": "`page` is not a positive integer or `per_page` is not an integer from 1 to 100; `errors` names each refused query parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/items/lookup": { "get": { "tags": [ "Backoffice - Inventory - Item Lookups" ], "summary": "Lookup Items for tenant forms", "operationId": "63b631f2f3ccacc860aee0864d7cb8a2", "parameters": [ { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "inventoried", "non-inventoried" ] } }, { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "active", "inactive" ] } }, { "name": "search", "in": "query", "description": "Matches part of the code, name, barcode or SKU; a blank one filters nothing.", "required": false, "schema": { "type": "string", "maxLength": 100 } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 200, "minimum": 1 } } ], "responses": { "200": { "description": "Minimal Item projection", "content": { "application/json": { "schema": { "properties": { "items": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "category_id": { "type": "string", "format": "uuid" }, "unit_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "type": { "type": "string", "enum": [ "inventoried", "non-inventoried" ] }, "sales_tax": { "description": "The active Item sales tax in this company; otherwise null.", "required": [ "id", "name", "rate", "kind" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "rate": { "type": "string" }, "kind": { "type": "string" } }, "type": "object", "nullable": true }, "default_purchase_unit_id": { "type": "string", "format": "uuid", "nullable": true }, "default_sales_unit_id": { "type": "string", "format": "uuid", "nullable": true }, "status": { "type": "string", "enum": [ "active", "inactive" ] } }, "type": "object" } }, "total": { "type": "integer" }, "per_page": { "type": "integer" }, "current_page": { "type": "integer" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Not a member of this tenant" }, "404": { "description": "Tenant not found" }, "422": { "description": "Invalid status filter or search text" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/items/search": { "get": { "tags": [ "Backoffice - Inventory - Item Search" ], "summary": "Search Items, exact match first", "description": "The cashier's item search (MER-3889). Tries an exact match among active Items, barcode first, then SKU, then code, and only then a paged text search over Item and Modelo names. The query is used whole and never decomposed: «1122-L» never yields the Talla L of Modelo «1122» (ADR 0273). With location_id every Item carries its Existencia, Reservado and Disponible there. Requires backoffice.inventory.items.view.", "operationId": "d88fde520dc7708c66fd882cf06b880d", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "q", "in": "query", "description": "Used whole: never split by hyphens, spaces or anything else; only the surrounding whitespace is trimmed. Exact barcode, then exact SKU (byte for byte), then code ignoring letter case, active Items only; otherwise names, ignoring letter case and accents. Unlike inventory/items/lookup?search, never matches part of a code, barcode or SKU.", "required": true, "schema": { "type": "string", "maxLength": 255, "minLength": 1 } }, { "name": "location_id", "in": "query", "description": "A Location of the company, of any status; adds on_hand_quantity, reserved_quantity and sellable_quantity to every Item. Blank counts as omitted. Any other UUID answers 404 location_not_found.", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "description": "Page of the text phase; ignored by exact matches.", "required": false, "schema": { "type": "integer", "default": 1, "maximum": 1000, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Bounds items and groups separately.", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 50, "minimum": 1 } } ], "responses": { "200": { "description": "The exact match, a page of the text phase, or none", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemSearchResult" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemMiddlewareError" } } } }, "403": { "description": "Missing backoffice.inventory.items.view (error_code null)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemProblem" } } } }, "404": { "description": "location_id is not a Location of the company (error_code location_not_found), or the middleware's message for an unknown company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemError" } } } }, "422": { "description": "Query validation, with errors by parameter (error_code null); q is refused when it is blank once trimmed. Callers that bypass this validator get the same bounds from the domain as invalid_item_search, without errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/items/{id}/unit-options": { "get": { "tags": [ "Backoffice - Inventory - Item Lookups" ], "summary": "Read the units a company member can select for an item", "operationId": "getItemUnitOptions", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Unit selector facts only", "content": { "application/json": { "schema": { "required": [ "units" ], "properties": { "units": { "type": "array", "items": { "required": [ "unit_id", "unit_name", "conversion_factor", "is_base_unit" ], "properties": { "unit_id": { "type": "string", "format": "uuid" }, "unit_name": { "type": "string", "nullable": true }, "conversion_factor": { "type": "string" }, "is_base_unit": { "type": "boolean" }, "is_purchase_default": { "description": "This is the item purchase unit preference.", "type": "boolean" }, "is_sales_default": { "description": "This is the item sale unit preference.", "type": "boolean" } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Not a member of this company" }, "404": { "description": "Item not found in this company" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/items/bulk-default-purchase-tax": { "post": { "tags": [ "Backoffice - Inventory Items" ], "summary": "Bulk-assign default purchase tax on inventory Items", "description": "Assigns one active company tax as «Impuesto de compra por defecto» on every selected Item. An inactive or foreign tax answers 422 item_default_purchase_tax_invalid and changes nothing; a missing Item id answers 404. Clearing a default stays on the single-Item PUT with null.", "operationId": "a40a5546275dba19289eb48f7651de23", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "ids", "default_purchase_tax_id" ], "properties": { "ids": { "description": "Item UUIDs to update; duplicates count once", "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1 }, "default_purchase_tax_id": { "description": "Active tax of the tenant company", "type": "string", "format": "uuid" } }, "type": "object" } } } }, "responses": { "200": { "description": "All selected Items updated", "content": { "application/json": { "schema": { "required": [ "updated_count" ], "properties": { "updated_count": { "type": "integer", "example": 3 } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemError" } } } }, "403": { "description": "Forbidden or tenant access refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemError" } } } }, "404": { "description": "A selected Item id is missing under the tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemError" } } } }, "422": { "description": "Laravel validation (error_code null) or item_default_purchase_tax_invalid; nothing written", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemError" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/items/bulk-default-sales-tax": { "post": { "tags": [ "Backoffice - Inventory Items" ], "summary": "Bulk-assign default sales tax on inventory Items", "description": "Assigns one active company tax as «Impuesto de venta por defecto» on every selected Item. An inactive or foreign tax answers 422 item_default_sales_tax_invalid and changes nothing; a missing Item id answers 404. Clearing a default stays on the single-Item PUT with null.", "operationId": "5cd193e5b289b42695910ff855529484", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "ids", "default_sales_tax_id" ], "properties": { "ids": { "description": "Item UUIDs to update; duplicates count once", "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1 }, "default_sales_tax_id": { "description": "Active tax of the tenant company", "type": "string", "format": "uuid" } }, "type": "object" } } } }, "responses": { "200": { "description": "All selected Items updated", "content": { "application/json": { "schema": { "required": [ "updated_count" ], "properties": { "updated_count": { "type": "integer", "example": 3 } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemError" } } } }, "403": { "description": "Forbidden or tenant access refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemError" } } } }, "404": { "description": "A selected Item id is missing under the tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemError" } } } }, "422": { "description": "Laravel validation (error_code null) or item_default_sales_tax_invalid; nothing written", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemError" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/items/{id}": { "get": { "tags": [ "Backoffice - Inventory Items" ], "summary": "Read an inventory Item", "description": "Requires one of backoffice.inventory.items.view, backoffice.purchases.purchases-invoices.view, backoffice.inventory.adjustments.view or backoffice.inventory.adjustments.create: the purchase invoice and the Adjustment form read the Item they name.", "operationId": "e80309a5b73965a864dad0dc9293336d", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "include_images", "in": "query", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Item with actual persisted metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemResource" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemError" } } } }, "403": { "description": "Forbidden or tenant access refused: none of the four permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemError" } } } }, "404": { "description": "Tenant-scoped resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemError" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Backoffice - Inventory Items" ], "summary": "Update an inventory Item", "description": "Omitted fiscal default remains unchanged; null clears it. Category may be changed using an optional nonnull company-owned UUID; omission preserves it. New categories must be active; the same persisted category remains valid when inactive, including equivalent UUID casing. Invalid category input returns 422; duplicate normalized name in the target category returns atomic 409. An omitted barcode or SKU keeps the stored one; null or blank clears it; a string sets it, trimmed and stored as written. A barcode or SKU another active Item uses answers 409 naming that Item, including on reactivation (status active), which then leaves the Item inactive and rolls the whole update back. Omitted sale_price keeps the stored Precio base; null clears it; an object {amount, currency} sets it, amount a string with up to 13 integer digits and 2 decimals, currency USD or VES. Omitted variant_group_id keeps the Item's Modelo and values, and variant_options must then be omitted too; null leaves the Modelo and frees its combination (variant_options null, omitted or []); a UUID joins, switches to or stays in that Modelo with exactly these values, one per option of the Modelo in any order. Staying in a Modelo deactivated since is allowed; joining or switching to an inactive one answers 422 item_variant_group_inactive. A combination of values another Item of the Modelo holds, in any status and ignoring letter case, answers 409 item_variant_combination_taken naming it. Code remains immutable. Existing transaction-aware unit rules remain enforced.", "operationId": "1cb29b9738008e567b4f9a3338b0aa23", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemUpdateInput" } } } }, "responses": { "200": { "description": "Updated; empty JSON object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemEmptyResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemError" } } } }, "403": { "description": "Forbidden or tenant access refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemError" } } } }, "404": { "description": "Tenant-scoped resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemError" } } } }, "409": { "description": "Duplicate normalized name and category, a barcode or SKU another active Item uses, a combination of values another Item of the Modelo holds, or a Modelo membership another request changed since the Item was read (item_concurrently_modified; reload and retry)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemConflict" } } } }, "422": { "description": "Laravel errors or domain error_code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemError" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/items/import": { "post": { "tags": [ "Backoffice - Inventory Items" ], "summary": "Import inventory items from an Excel file", "description": "Starts an asynchronous import of catalog items from an Excel file. Requires backoffice.inventory.items.create. A row may make its Item a Variante of a Modelo (columns M–S): joining an existing active Modelo needs nothing more; creating a Modelo the file names also needs backoffice.inventory.items.update, otherwise that row is refused.", "operationId": "d86aa4816c776b8bc471e42eb59ce4ba", "parameters": [ { "name": "tenant", "in": "path", "description": "Company tenant ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "file" ], "properties": { "file": { "description": "Excel .xls/.xlsx file; maximum 5 MiB; both MIME and extension validated", "type": "string", "format": "binary" } }, "type": "object" } } } }, "responses": { "202": { "description": "Import started successfully", "content": { "application/json": { "schema": { "required": [ "success", "import_id", "message" ], "properties": { "success": { "type": "boolean" }, "import_id": { "type": "string", "format": "uuid" }, "message": { "type": "string" } }, "type": "object" } } } }, "403": { "description": "Unauthorized - User does not have permission to import items", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemError" } } } }, "422": { "description": "Validation error - Invalid file format or missing file", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/items/import/{importId}/status": { "get": { "tags": [ "Backoffice - Inventory Items" ], "summary": "Get item import status", "description": "Returns the current status of an inventory item import job", "operationId": "b5d0aab574ac10a527cab9be87e158e8", "parameters": [ { "name": "tenant", "in": "path", "description": "Company tenant ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "importId", "in": "path", "description": "Import job ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Import status retrieved successfully", "content": { "application/json": { "schema": { "required": [ "id", "status", "progress", "imported_count", "skipped_count", "total_count", "errors", "warnings", "original_filename", "started_at", "completed_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed" ] }, "progress": { "type": "integer" }, "imported_count": { "type": "integer" }, "skipped_count": { "type": "integer" }, "total_count": { "type": "integer" }, "errors": { "type": "array", "items": { "type": "string" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "original_filename": { "type": "string" }, "started_at": { "type": "string", "format": "date-time", "nullable": true }, "completed_at": { "type": "string", "format": "date-time", "nullable": true } }, "type": "object" } } } }, "404": { "description": "Import job not found or belongs to another company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemProblem" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemError" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/items": { "get": { "tags": [ "Backoffice - Inventory Items" ], "summary": "Search inventory Items with independent facets", "description": "Requires backoffice.inventory.items.view on the route; cross-module catalogs use /items/lookup. Values OR within fields and AND across fields. Status facet excludes only status; label facet excludes only label_ids. Grouping active before inactive precedes pagination; code DESC by default with ID tie in selected direction.", "operationId": "efe26b9ddf5d59209733ac15801009b1", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "search", "in": "query", "schema": { "type": "string" } }, { "name": "name", "in": "query", "schema": { "type": "string" } }, { "name": "code", "in": "query", "schema": { "type": "string" } }, { "name": "location_id", "in": "query", "description": "Scope all quantities to this location; item average costs and catalog membership are unchanged. Omit for company totals.", "schema": { "type": "string", "format": "uuid" } }, { "name": "barcode", "in": "query", "description": "Exact, case-sensitive match on any status. Blank is ignored. Search never matches it.", "schema": { "type": "string", "maxLength": 64 } }, { "name": "sku", "in": "query", "description": "Exact, case-sensitive match on any status. Blank is ignored. Search never matches it.", "schema": { "type": "string", "maxLength": 64 } }, { "name": "variant_group_id", "in": "query", "description": "Only the Items of this Modelo, of any status unless status narrows them; meta.counts and meta.label_counts honour it. Blank is ignored; a value that is not a UUID answers 422.", "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "active", "inactive", "all", "" ] } }, { "name": "status[]", "in": "query", "schema": { "type": "array", "items": { "type": "string", "enum": [ "active", "inactive" ] } } }, { "name": "type", "in": "query", "schema": { "type": "string", "enum": [ "inventoried", "non-inventoried", "all", "" ] } }, { "name": "type[]", "in": "query", "schema": { "type": "array", "items": { "type": "string", "enum": [ "inventoried", "non-inventoried" ] } } }, { "name": "without_tax", "in": "query", "description": "Only Items missing a purchase OR sales tax; each Item appears once. Combines with other filters.", "schema": { "type": "string", "enum": [ "1" ] } }, { "name": "without_purchase_tax", "in": "query", "description": "Only Items with no purchase tax. Combines with every other filter; omitted leaves taxes unrestricted.", "schema": { "type": "string", "enum": [ "1" ] } }, { "name": "without_sales_tax", "in": "query", "description": "Only Items with no sales tax. Combines with every other filter; omitted leaves taxes unrestricted.", "schema": { "type": "string", "enum": [ "1" ] } }, { "name": "category_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "category_id[]", "in": "query", "schema": { "type": "array", "items": { "type": "string", "format": "uuid" } } }, { "name": "label_ids", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "label_ids[]", "in": "query", "schema": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 20 } }, { "name": "sort_by", "in": "query", "schema": { "type": "string", "default": "code", "enum": [ "code", "name", "created_at" ] } }, { "name": "sort_order", "in": "query", "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } }, { "name": "group_by", "in": "query", "schema": { "type": "string", "enum": [ "status" ] } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "Items page", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemPage" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemError" } } } }, "403": { "description": "Forbidden or tenant access refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemError" } } } }, "422": { "description": "Field validation failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemError" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Inventory Items" ], "summary": "Create an inventory Item", "description": "Client supplies the Item UUID; successful response is an empty JSON object. Creation always starts active. Barcode and SKU are optional opaque identifiers: trimmed and stored as written, never parsed; absent, null or blank means none, and on multipart an empty key must be omitted (the string null is stored literally). Each is unique per company among active Items; a collision answers 409 naming the existing Item. At least one account and one unit with exactly one base unit. Factors remain positive decimal strings. Buffered create images accept jpeg/jpg/png/webp/gif up to 10 MiB each; alt text up to 255 characters. An image larger than 4000x4000 is stored turned upright by its EXIF orientation, scaled down to fit inside 4000x4000 keeping its proportions and re-encoded in its own format; the Item records its stored width and height. A file the server cannot use as an image (unreadable, not JPG/PNG/WebP/GIF, or over 10 MiB) answers 422 item_image_invalid with errors[\"images.\"] naming its position. Nothing is created. The first uploaded file becomes primary; image_alt_texts follows the file order. Optional sale_price is the Precio base: amount a string with up to 13 integer digits and 2 decimals, stored at exactly 2, currency USD or VES; omit it or send null for none, and in multipart/form-data send sale_price[amount] and sale_price[currency]. Optional variant_group_id makes the Item a Variante of that Modelo (a Modelo of the company, active): variant_options must then hold exactly one {name, value} per option of the Modelo, in any order, names matched ignoring letter case and spacing; they are stored in the Modelo's order and spelling. Omit both for no Modelo; in multipart/form-data send variant_options[i][name] and variant_options[i][value], and omit both keys when there is no Modelo. A combination of values another Item of the Modelo holds, in any status and ignoring letter case, answers 409 item_variant_combination_taken naming it; an inactive Modelo answers 422 item_variant_group_inactive; options that do not match answer 422 item_variant_options_mismatch with missing_options and unexpected_options.", "operationId": "014682ef7c8f0c2bef8dceeef5395b90", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ItemCreateInput" }, { "properties": { "images": { "type": "array", "items": { "type": "string", "format": "binary" }, "maxItems": 10 }, "image_alt_texts": { "type": "array", "items": { "type": "string", "maxLength": 255 } } }, "type": "object" } ] } }, "application/json": { "schema": { "$ref": "#/components/schemas/ItemCreateInput" } } } }, "responses": { "201": { "description": "Created; empty JSON object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemEmptyResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemError" } } } }, "403": { "description": "Forbidden or tenant access refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemError" } } } }, "409": { "description": "Duplicate normalized name and category, a barcode or SKU another active Item uses, or a combination of values another Item of the Modelo holds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemConflict" } } } }, "422": { "description": "Laravel errors, or a domain error_code such as item_image_invalid (errors[\"images.\"])", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemError" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/items/purchase-tax-lookup/{id}": { "get": { "tags": [ "Backoffice - Inventory Items" ], "summary": "Read only the active Item purchase tax for a company-member purchase line editor", "operationId": "ac80bcd2924c394db3f061fc1171ece1", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "No configured or active purchase tax returns null; no company fallback", "content": { "application/json": { "schema": { "required": [ "purchase_tax" ], "properties": { "purchase_tax": { "required": [ "id", "name", "rate", "kind" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "rate": { "type": "string" }, "kind": { "type": "string" } }, "type": "object", "nullable": true } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Not a member of this company" }, "404": { "description": "Item absent from this company" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/items/template-import": { "get": { "tags": [ "Backoffice - Inventory Items" ], "summary": "Download inventory items import template", "description": "Downloads an Excel template file for importing inventory items. The item code is assigned by the system and is not part of the template.", "operationId": "1216ed0238d041d3359697a19cd21121", "parameters": [ { "name": "tenant", "in": "path", "description": "Company tenant ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Excel template file downloaded successfully", "headers": { "Cache-Control": { "description": "Always no-store: the workbook is never cached", "schema": { "type": "string", "example": "no-store, private" } } }, "content": { "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "format": "binary" } } } }, "403": { "description": "Problem JSON, title Forbidden. Without backoffice.inventory.items.view the route can: middleware answers with error_code and errors null; the tenant middleware stack (API-key guardrails, company access, tenant membership) answers without error_code, with a reason only from tenant membership.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ImportTemplateProblem" }, { "$ref": "#/components/schemas/ImportTemplateMiddlewareForbidden" } ] } } } }, "500": { "description": "Unexpected failure, reported. Problem JSON with error_code and errors null; the detail is generic in production.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportTemplateProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/locations/lookup": { "get": { "tags": [ "Backoffice - Inventory - Location Lookups" ], "summary": "Lookup Locations for tenant forms", "operationId": "82f2ee919bc8e13ef7a7b7c0128b1296", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "active", "inactive" ] } }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "inventoried", "services", "not_inventoried" ] } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 200, "minimum": 1 } } ], "responses": { "200": { "description": "Minimal Location projection", "content": { "application/json": { "schema": { "properties": { "items": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "type": { "type": "string", "enum": [ "inventoried", "services", "not_inventoried" ] } }, "type": "object" } }, "total": { "type": "integer" }, "per_page": { "type": "integer" }, "current_page": { "type": "integer" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Not a member of this tenant" }, "404": { "description": "Tenant not found" }, "422": { "description": "Invalid status or type filter" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/locations/{id}": { "get": { "tags": [ "Backoffice - Inventory Locations" ], "summary": "Get a location by ID", "operationId": "04f27b9a7e960392e8eaef3e5ebd0c88", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Location details", "content": { "application/json": { "schema": { "required": [ "id", "code", "name", "description", "type", "status", "company_id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "type": { "type": "string", "enum": [ "services", "not_inventoried", "inventoried" ] }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "company_id": { "type": "string", "format": "uuid" } }, "type": "object" } } } }, "403": { "description": "Unauthorized" }, "404": { "description": "Location not found" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Backoffice - Inventory Locations" ], "summary": "Update an existing location", "operationId": "4fb03ff43cedccc0ab0d28693f8b6aec", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "name": { "type": "string", "example": "Updated Warehouse", "maxLength": 100, "minLength": 3 }, "description": { "type": "string", "example": "Updated warehouse description", "nullable": true, "maxLength": 255 }, "type": { "type": "string", "example": "not_inventoried", "enum": [ "services", "not_inventoried", "inventoried" ] }, "status": { "type": "string", "example": "active", "enum": [ "active", "inactive" ] } }, "type": "object" } } } }, "responses": { "200": { "description": "Location updated successfully" }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocationValidationProblem" } } } }, "403": { "description": "Unauthorized" }, "404": { "description": "Location not found" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/locations": { "get": { "tags": [ "Backoffice - Inventory Locations" ], "summary": "Search locations", "operationId": "36c56fc52f6f755e04ebe23bd5032ae5", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "status[]", "in": "query", "description": "Union of statuses; omit or send an empty array for all.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "active", "inactive" ] } } }, { "name": "type[]", "in": "query", "description": "Union of location types; omit or send an empty array for all.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "services", "not_inventoried", "inventoried" ] } } }, { "name": "sort_by", "in": "query", "schema": { "type": "string", "default": "code", "enum": [ "code", "name", "created_at" ] } }, { "name": "sort_order", "in": "query", "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } }, { "name": "group_by", "in": "query", "description": "Active group before inactive, then the selected sort and ID, before pagination.", "schema": { "type": "string", "enum": [ "status" ] } }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "active", "inactive", "all" ] } }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "services", "not_inventoried", "inventoried", "all" ] } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "List of locations", "content": { "application/json": { "schema": { "required": [ "items", "total", "per_page", "current_page", "meta" ], "properties": { "items": { "type": "array", "items": { "required": [ "id", "code", "name", "description", "type", "status", "company_id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "type": { "type": "string", "enum": [ "services", "not_inventoried", "inventoried" ] }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "company_id": { "type": "string", "format": "uuid" } }, "type": "object" } }, "total": { "type": "integer" }, "per_page": { "type": "integer" }, "current_page": { "type": "integer" }, "meta": { "required": [ "counts" ], "properties": { "counts": { "description": "Counts retain tenant, type and search; exclude status and pagination.", "required": [ "active", "inactive" ], "properties": { "active": { "type": "integer", "minimum": 0 }, "inactive": { "type": "integer", "minimum": 0 } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "422": { "description": "Invalid query values", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocationValidationProblem" } } } }, "403": { "description": "Forbidden: requires the locations view permission" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Inventory Locations" ], "summary": "Create a new location", "operationId": "518ce6def30038b5e6e5e0254f21542d", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "id", "code", "name", "type" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000" }, "code": { "type": "string", "example": "LOC001", "maxLength": 20, "minLength": 3 }, "name": { "type": "string", "example": "Main Warehouse", "maxLength": 100, "minLength": 3 }, "description": { "type": "string", "example": "Main warehouse for storing products", "nullable": true, "maxLength": 255 }, "type": { "type": "string", "example": "services", "enum": [ "services", "not_inventoried", "inventoried" ] } }, "type": "object" } } } }, "responses": { "201": { "description": "Location created successfully" }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocationValidationProblem" } } } }, "403": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/settings/categories": { "get": { "tags": [ "Backoffice - Inventory - Settings - Categories" ], "summary": "List ItemCategories", "operationId": "aa6386248ca66a7544f223e84205b05b", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 100, "minimum": 1 } }, { "name": "search", "in": "query", "description": "Name or description search; empty means omitted.", "schema": { "type": "string", "nullable": true } }, { "name": "name", "in": "query", "schema": { "type": "string", "nullable": true } }, { "name": "description", "in": "query", "schema": { "type": "string", "nullable": true } }, { "name": "status", "in": "query", "description": "Omitted, empty or all means all statuses.", "schema": { "type": "string", "enum": [ "active", "inactive", "all" ] } }, { "name": "status[]", "in": "query", "description": "Flat union of statuses. Empty list means all; all is not a list member.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "active", "inactive" ] } } }, { "name": "sort_by", "in": "query", "description": "Default name ASC; explicit selected field without direction defaults DESC. Bare fields only.", "schema": { "type": "string", "default": "name", "enum": [ "name", "created_at" ] } }, { "name": "sort_order", "in": "query", "description": "Canonical direction, trimmed and case normalized. Empty means omitted.", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "sort_direction", "in": "query", "description": "Compatible alias. Both direction keys must normalize to the same value or 422 under sort_direction.", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "group_by", "in": "query", "description": "Opt-in active before inactive, selected sort and ID tie before pagination. Omitted preserves ungrouped order.", "schema": { "type": "string", "enum": [ "status" ] } } ], "responses": { "200": { "description": "Page with status-independent facets", "content": { "application/json": { "schema": { "required": [ "items", "total", "per_page", "current_page", "meta" ], "properties": { "items": { "type": "array", "items": { "required": [ "id", "name", "description", "status", "company_id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "company_id": { "type": "string", "format": "uuid" } }, "type": "object" } }, "total": { "type": "integer" }, "per_page": { "type": "integer" }, "current_page": { "type": "integer" }, "meta": { "required": [ "counts" ], "properties": { "counts": { "description": "Retains company, search, name and description; excludes status, pagination, sort and grouping.", "required": [ "active", "inactive" ], "properties": { "active": { "type": "integer", "minimum": 0 }, "inactive": { "type": "integer", "minimum": 0 } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "422": { "description": "Field validation errors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventorySettingsValidationProblem" } } } }, "401": { "description": "Authentication middleware", "content": { "application/json": { "schema": { "required": [ "message" ], "properties": { "message": { "type": "string" } }, "type": "object" } } } }, "403": { "description": "Permission denied by middleware or controller", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/InventorySettingsForbidden" }, { "$ref": "#/components/schemas/InventorySettingsControllerProblem" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Inventory - Settings - Categories" ], "summary": "Post ItemCategories", "operationId": "356950a6f315338e192e5a9cf60b7ad6", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "id", "name" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "maxLength": 80, "minLength": 3 }, "description": { "description": "Optional; omission stores null", "type": "string", "nullable": true, "maxLength": 255 } }, "type": "object" } } } }, "responses": { "201": { "description": "Completion acknowledgement: empty JSON object, no returned entity", "content": { "application/json": { "schema": { "maxProperties": 0, "type": "object" } } } }, "422": { "description": "Field validation errors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventorySettingsValidationProblem" } } } }, "401": { "description": "Authentication middleware", "content": { "application/json": { "schema": { "required": [ "message" ], "properties": { "message": { "type": "string" } }, "type": "object" } } } }, "403": { "description": "Permission denied by middleware or controller", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/InventorySettingsForbidden" }, { "$ref": "#/components/schemas/InventorySettingsControllerProblem" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/settings/categories/{id}": { "get": { "tags": [ "Backoffice - Inventory - Settings - Categories" ], "summary": "Detail ItemCategories", "operationId": "f1b90df93b1f5876a7aba4361c040171", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Record", "content": { "application/json": { "schema": { "required": [ "id", "name", "description", "status", "company_id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "company_id": { "type": "string", "format": "uuid" } }, "type": "object" } } } }, "404": { "description": "Missing or foreign-company record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventorySettingsControllerProblem" } } } }, "401": { "description": "Authentication middleware", "content": { "application/json": { "schema": { "required": [ "message" ], "properties": { "message": { "type": "string" } }, "type": "object" } } } }, "403": { "description": "Permission denied by middleware or controller", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/InventorySettingsForbidden" }, { "$ref": "#/components/schemas/InventorySettingsControllerProblem" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Backoffice - Inventory - Settings - Categories" ], "summary": "Put ItemCategories", "operationId": "9fecd96b1580aa2eae30c6d72f559702", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name" ], "properties": { "name": { "type": "string", "maxLength": 80, "minLength": 3 }, "description": { "description": "Optional; omission stores null", "type": "string", "nullable": true, "maxLength": 255 }, "status": { "description": "Optional; omission preserves current status", "type": "string", "enum": [ "active", "inactive" ] } }, "type": "object" } } } }, "responses": { "200": { "description": "Completion acknowledgement: empty JSON object, no returned entity", "content": { "application/json": { "schema": { "maxProperties": 0, "type": "object" } } } }, "422": { "description": "Field validation errors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventorySettingsValidationProblem" } } } }, "404": { "description": "Missing or foreign-company record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventorySettingsControllerProblem" } } } }, "401": { "description": "Authentication middleware", "content": { "application/json": { "schema": { "required": [ "message" ], "properties": { "message": { "type": "string" } }, "type": "object" } } } }, "403": { "description": "Permission denied by middleware or controller", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/InventorySettingsForbidden" }, { "$ref": "#/components/schemas/InventorySettingsControllerProblem" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/settings/units/{id}": { "get": { "tags": [ "Backoffice - Inventory - Settings - Units" ], "summary": "Detail Units", "operationId": "e5a40b8a3bfb2e8589fb36adda3435ab", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Record", "content": { "application/json": { "schema": { "required": [ "id", "name", "description", "status", "company_id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "company_id": { "type": "string", "format": "uuid" } }, "type": "object" } } } }, "404": { "description": "Missing or foreign-company record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventorySettingsControllerProblem" } } } }, "401": { "description": "Authentication middleware", "content": { "application/json": { "schema": { "required": [ "message" ], "properties": { "message": { "type": "string" } }, "type": "object" } } } }, "403": { "description": "Permission denied by middleware or controller", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/InventorySettingsForbidden" }, { "$ref": "#/components/schemas/InventorySettingsControllerProblem" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Backoffice - Inventory - Settings - Units" ], "summary": "Put Units", "operationId": "338e2b46b3c23a9fc47798cf6e98183a", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name" ], "properties": { "name": { "type": "string", "maxLength": 255, "minLength": 1 }, "description": { "description": "Optional; omission stores null", "type": "string", "nullable": true, "maxLength": 255 }, "status": { "description": "Optional; omission preserves current status", "type": "string", "enum": [ "active", "inactive" ] } }, "type": "object" } } } }, "responses": { "200": { "description": "Completion acknowledgement: empty JSON object, no returned entity", "content": { "application/json": { "schema": { "maxProperties": 0, "type": "object" } } } }, "422": { "description": "Field validation errors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventorySettingsValidationProblem" } } } }, "404": { "description": "Missing or foreign-company record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventorySettingsControllerProblem" } } } }, "401": { "description": "Authentication middleware", "content": { "application/json": { "schema": { "required": [ "message" ], "properties": { "message": { "type": "string" } }, "type": "object" } } } }, "403": { "description": "Permission denied by middleware or controller", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/InventorySettingsForbidden" }, { "$ref": "#/components/schemas/InventorySettingsControllerProblem" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/settings/units": { "get": { "tags": [ "Backoffice - Inventory - Settings - Units" ], "summary": "List Units", "operationId": "1283ef26986d5994e2f1ae5396be2467", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 100, "minimum": 1 } }, { "name": "search", "in": "query", "description": "Name or description search; empty means omitted.", "schema": { "type": "string", "nullable": true } }, { "name": "name", "in": "query", "schema": { "type": "string", "nullable": true } }, { "name": "description", "in": "query", "schema": { "type": "string", "nullable": true } }, { "name": "status", "in": "query", "description": "Omitted, empty or all means all statuses.", "schema": { "type": "string", "enum": [ "active", "inactive", "all" ] } }, { "name": "status[]", "in": "query", "description": "Flat union of statuses. Empty list means all; all is not a list member.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "active", "inactive" ] } } }, { "name": "sort_by", "in": "query", "description": "Default name ASC; explicit selected field without direction defaults DESC. Bare fields only.", "schema": { "type": "string", "default": "name", "enum": [ "name", "created_at" ] } }, { "name": "sort_order", "in": "query", "description": "Canonical direction, trimmed and case normalized. Empty means omitted.", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "sort_direction", "in": "query", "description": "Compatible alias. Both direction keys must normalize to the same value or 422 under sort_direction.", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "group_by", "in": "query", "description": "Opt-in active before inactive, selected sort and ID tie before pagination. Omitted preserves ungrouped order.", "schema": { "type": "string", "enum": [ "status" ] } } ], "responses": { "200": { "description": "Page with status-independent facets", "content": { "application/json": { "schema": { "required": [ "items", "total", "per_page", "current_page", "meta" ], "properties": { "items": { "type": "array", "items": { "required": [ "id", "name", "description", "status", "company_id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "company_id": { "type": "string", "format": "uuid" } }, "type": "object" } }, "total": { "type": "integer" }, "per_page": { "type": "integer" }, "current_page": { "type": "integer" }, "meta": { "required": [ "counts" ], "properties": { "counts": { "description": "Retains company, search, name and description; excludes status, pagination, sort and grouping.", "required": [ "active", "inactive" ], "properties": { "active": { "type": "integer", "minimum": 0 }, "inactive": { "type": "integer", "minimum": 0 } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "422": { "description": "Field validation errors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventorySettingsValidationProblem" } } } }, "401": { "description": "Authentication middleware", "content": { "application/json": { "schema": { "required": [ "message" ], "properties": { "message": { "type": "string" } }, "type": "object" } } } }, "403": { "description": "Permission denied by middleware or controller", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/InventorySettingsForbidden" }, { "$ref": "#/components/schemas/InventorySettingsControllerProblem" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Inventory - Settings - Units" ], "summary": "Post Units", "operationId": "ad2b7cb9896fb7109fc90da8ca560d31", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "id", "name" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "maxLength": 255, "minLength": 1 }, "description": { "description": "Optional; omission stores null", "type": "string", "nullable": true, "maxLength": 255 } }, "type": "object" } } } }, "responses": { "201": { "description": "Completion acknowledgement: empty JSON object, no returned entity", "content": { "application/json": { "schema": { "maxProperties": 0, "type": "object" } } } }, "422": { "description": "Field validation errors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventorySettingsValidationProblem" } } } }, "401": { "description": "Authentication middleware", "content": { "application/json": { "schema": { "required": [ "message" ], "properties": { "message": { "type": "string" } }, "type": "object" } } } }, "403": { "description": "Permission denied by middleware or controller", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/InventorySettingsForbidden" }, { "$ref": "#/components/schemas/InventorySettingsControllerProblem" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/transfers/{id}/cancel": { "post": { "tags": [ "Backoffice - Inventory - Transfers" ], "summary": "Cancel a pending inventory transfer", "description": "Cancel a pending inventory transfer that has no dispatch or whose dispatch has not dispatched any stock. Cascades cancellation when an associated pending inventory dispatch exists.", "operationId": "cancelInventoryTransfer", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "Inventory transfer ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Inventory transfer cancelled successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryTransferResource" } } } }, "401": { "description": "Unauthenticated (Laravel Sanctum)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryTransferUnauthenticated" } } } }, "403": { "description": "Forbidden - insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryTransferProblem" } } } }, "404": { "description": "Inventory transfer not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryTransferProblem" } } } }, "409": { "description": "Transfer cannot be cancelled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryTransferProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/transfers/{id}/enhanced": { "get": { "tags": [ "Backoffice - Inventory - Transfers" ], "summary": "Get an enhanced inventory transfer by id", "operationId": "getEnhancedInventoryTransfer", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Enhanced inventory transfer detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryTransferEnhancedResource" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryTransferUnauthenticated" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryTransferForbidden" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryTransferProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/transfers/{id}": { "get": { "tags": [ "Backoffice - Inventory - Transfers" ], "summary": "Get an inventory transfer by id", "operationId": "getInventoryTransfer", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Inventory transfer detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryTransferResource" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryTransferUnauthenticated" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryTransferForbidden" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryTransferProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/transfers/{id}/guide": { "put": { "tags": [ "Backoffice - Inventory - Transfers" ], "summary": "Record the external dispatch guide reference", "operationId": "090d42e08e3525c1478db1886fc8687a", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "guide_number", "guide_control" ], "properties": { "guide_number": { "type": "string", "nullable": true, "maxLength": 255 }, "guide_control": { "type": "string", "nullable": true, "maxLength": 255 } }, "type": "object" } } } }, "responses": { "200": { "description": "Reference saved" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "404": { "description": "Movement not found" }, "422": { "description": "Invalid reference" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/transfers": { "get": { "tags": [ "Backoffice - Inventory - Transfers" ], "summary": "List inventory transfers", "operationId": "listInventoryTransfers", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "description": "Legacy scalar filter", "schema": { "type": "string", "enum": [ "pending", "in_transit", "received", "cancelled", "all" ] } }, { "name": "status[]", "in": "query", "description": "Flat list; OR within field", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "pending", "in_transit", "received", "cancelled" ] } } }, { "name": "origin_location_id", "in": "query", "description": "Legacy scalar filter", "schema": { "type": "string", "format": "uuid" } }, { "name": "origin_location_id[]", "in": "query", "description": "Flat list; OR within field", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" } } }, { "name": "destination_location_id", "in": "query", "description": "Legacy scalar filter", "schema": { "type": "string", "format": "uuid" } }, { "name": "destination_location_id[]", "in": "query", "description": "Flat list; OR within field", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" } } }, { "name": "user_id", "in": "query", "description": "Legacy scalar filter", "schema": { "type": "string", "pattern": "^\\d+$" } }, { "name": "user_id[]", "in": "query", "description": "Flat list; OR within field", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "pattern": "^\\d+$" } } }, { "name": "responsible_user_id", "in": "query", "description": "Legacy scalar filter", "schema": { "type": "string", "pattern": "^\\d+$" } }, { "name": "responsible_user_id[]", "in": "query", "description": "Flat list; OR within field", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "pattern": "^\\d+$" } } }, { "name": "label_ids", "in": "query", "description": "Legacy scalar filter", "schema": { "type": "string", "format": "uuid" } }, { "name": "label_ids[]", "in": "query", "description": "Flat list; OR within field", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 20 } }, { "name": "search_query", "in": "query", "schema": { "type": "string" } }, { "name": "search", "in": "query", "schema": { "type": "string" } }, { "name": "code", "in": "query", "schema": { "type": "string" } }, { "name": "date_from", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "date_to", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 100, "minimum": 1 } }, { "name": "sort_by", "in": "query", "schema": { "type": "string", "default": "code", "enum": [ "code", "date", "delivery_date" ] } }, { "name": "sort_order", "in": "query", "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } }, { "name": "group_by", "in": "query", "schema": { "type": "string", "enum": [ "status" ] } } ], "responses": { "200": { "description": "Paginated inventory transfers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryTransfersPage" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryTransferUnauthenticated" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryTransferForbidden" } } } }, "422": { "description": "Field validation errors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryTransferProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Inventory - Transfers" ], "summary": "Create an inventory transfer", "description": "Creates an inventory transfer and its originating inventory dispatch atomically", "operationId": "createInventoryTransfer", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "date", "origin_location_id", "destination_location_id", "items" ], "properties": { "date": { "description": "Calendar-day input used by clients; legacy Laravel-valid dates remain accepted and are stored as local datetime strings.", "type": "string", "format": "date" }, "origin_location_id": { "type": "string", "format": "uuid" }, "destination_location_id": { "type": "string", "format": "uuid" }, "user_id": { "type": "string", "nullable": true }, "responsible_user_id": { "type": "string", "nullable": true }, "observations": { "type": "string", "nullable": true }, "items": { "type": "array", "items": { "required": [ "id", "item_id", "category_id", "expected_quantity", "unit_id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "item_id": { "type": "string", "format": "uuid" }, "category_id": { "type": "string", "format": "uuid" }, "expected_quantity": { "description": "DECIMAL(15,4) numeric string; max 11 integer digits and 4 fractional digits; must be greater than zero", "type": "string", "pattern": "^(?!0+(?:\\.0+)?$)\\d{1,11}(\\.\\d{1,4})?$", "example": "5.0000" }, "unit_id": { "type": "string", "format": "uuid" } }, "type": "object" }, "minItems": 1 } }, "type": "object" } } } }, "responses": { "201": { "description": "Inventory transfer created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryTransferResource" } } } }, "400": { "description": "Bad request: ApiController problem payload (invalid item-unit combination)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryTransferProblem" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryTransferUnauthenticated" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryTransferForbidden" } } } }, "422": { "description": "Field validation errors including date and decimal quantity, invalid assigned user, dispatch domain error, or incomplete accounting configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryTransferProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/transfers/{id}/responsible": { "put": { "tags": [ "Backoffice - Inventory - Transfers" ], "summary": "Reassign the responsible user of an inventory transfer", "operationId": "reassignInventoryTransferResponsible", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "responsible_user_id" ], "properties": { "responsible_user_id": { "description": "Company user id that becomes the Inventory Transfer Responsable; null clears it", "type": "string", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Responsible reassigned or valid no-op", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryTransferResponsibleAcknowledgement" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryTransferUnauthenticated" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryTransferForbidden" } } } }, "404": { "description": "Inventory transfer not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryTransferProblem" } } } }, "409": { "description": "Responsible cannot be reassigned in the current status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryTransferProblem" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryTransferProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/transformations/{id}/complete": { "put": { "tags": [ "Backoffice - Inventory Transformations" ], "summary": "Save the header and lines of a transformation (Transformación de ítems)", "description": "Replaces the header and every line of an open transformation at the version the client read; the version moves by 2. A stale version is a conflict and overwrites nothing. responsible_user_id is accepted and ignored.", "operationId": "ebf9cdd0e6f3bbeb562487342ff3038c", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "Transformation ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransformationCompleteRequest" } } } }, "responses": { "200": { "description": "Saved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransformationCompleted" } } } }, "401": { "description": "HTTP 401", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransformationUnauthenticated" } } } }, "403": { "description": "HTTP 403; needs backoffice.inventory.transformations.update", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransformationForbidden" } } } }, "404": { "description": "HTTP 404; transformation_not_found for a missing transformation or one of another company", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/TransformationProblem" }, { "$ref": "#/components/schemas/TransformationUnauthenticated" } ] } } } }, "409": { "description": "HTTP 409; transformation_version_conflict when another write saved first, transformation_cannot_be_modified (with transformation_status) for a procesada or anulada transformation", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/TransformationProblem" }, { "$ref": "#/components/schemas/TransformationClosedProblem" } ] } } } }, "400": { "description": "HTTP 400; the lines break an aggregate invariant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransformationProblem" } } } }, "422": { "description": "HTTP 422; errors names the field: lines for a missing input or output, lines.N.id for a repeated id, lines.N.expected_quantity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransformationProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/transformations/{id}/calculate-costs": { "put": { "tags": [ "Backoffice - Inventory Transformations" ], "summary": "Calculate transformation costs in both books", "description": "Deprecated: no first-party client calls it and processing discards stored costs. Values every input at each book's current average of its item and shares each book's input total among the outputs by produced quantity, the last output taking each book's remainder (ADR 0248). Typed costs are not kept. The costs are saved on the lines under the row lock; processing values them again under the stock lock.", "operationId": "b0c838709b3ebc03871fff7c713e132a", "parameters": [ { "name": "tenant", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "description": "Transformation ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "version": { "description": "Transformation version the client read", "type": "integer", "example": 1, "minimum": 1 }, "correlation_id": { "description": "Correlation identifier for tracing", "type": "string", "maxLength": 255 } }, "type": "object" } } } }, "responses": { "200": { "description": "Costs calculated in both books", "content": { "application/json": { "schema": { "properties": { "transformation_id": { "type": "string", "format": "uuid" }, "message": { "type": "string", "example": "Costos calculados exitosamente" }, "cost_summary": { "properties": { "input_total_cost": { "description": "Sum of the inputs' functional total costs, scale 8.", "type": "string", "example": "3400.00000000" }, "output_total_cost": { "description": "Sum of the outputs' functional total costs, scale 8.", "type": "string", "example": "3400.00000000" }, "reporting_input_total_cost": { "description": "Sum of the inputs' reporting total costs, scale 8. Null while no input carries a reporting cost.", "type": "string", "example": "30.00000000", "nullable": true }, "reporting_output_total_cost": { "description": "Sum of the outputs' reporting total costs, scale 8. Null while no output carries a reporting cost.", "type": "string", "example": "30.00000000", "nullable": true }, "lines_updated": { "type": "integer", "example": 3 } }, "type": "object" }, "lines": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "item_id": { "type": "string", "format": "uuid" }, "item_name": { "type": "string", "nullable": true }, "type": { "type": "string", "enum": [ "input", "output" ] }, "expected_quantity": { "type": "string", "example": "3.00000000" }, "consumed_quantity": { "type": "string", "example": "0.00000000" }, "produced_quantity": { "type": "string", "example": "3.00000000" }, "unit_cost": { "description": "Cost of one unit in the functional book, scale 8.", "type": "string", "example": "1133.33333333", "nullable": true }, "total_cost": { "description": "Cost of the line's quantity in the functional book, scale 8.", "type": "string", "example": "3400.00000000", "nullable": true }, "reporting_unit_cost": { "description": "Cost of one unit in the reporting book, scale 8.", "type": "string", "example": "10.00000000", "nullable": true }, "reporting_total_cost": { "description": "Cost of the line's quantity in the reporting book, scale 8.", "type": "string", "example": "30.00000000", "nullable": true }, "company_id": { "type": "string", "format": "uuid" } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "HTTP 401", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransformationUnauthenticated" } } } }, "404": { "description": "HTTP 404; transformation_not_found for a missing transformation or one of another company", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/TransformationProblem" }, { "$ref": "#/components/schemas/TransformationUnauthenticated" } ] } } } }, "409": { "description": "HTTP 409; transformation_cannot_be_modified for a procesada or anulada transformation", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/TransformationProblem" }, { "$ref": "#/components/schemas/TransformationClosedProblem" } ] } } } }, "422": { "description": "HTTP 422", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransformationProblem" } } } }, "403": { "description": "The user may not change the transformation's status", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unauthorized" }, "status": { "type": "integer", "example": 403 }, "detail": { "type": "string", "example": "You do not have permission to access this resource." } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "deprecated": true, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/transformations/{id}": { "get": { "tags": [ "Transformations" ], "summary": "Get transformation by ID", "description": "The record, in the list row's shape, with each book's cost (ADR 0248). Inputs are valued at each book's average at processing; outputs share each book's input total. Reporting values are null before valuation or for transformations processed before MER-3710.", "operationId": "getTransformation", "parameters": [ { "name": "tenant", "in": "path", "description": "Tenant ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "Transformation ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Transformation retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransformationResource" } } } }, "401": { "description": "HTTP 401", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransformationUnauthenticated" } } } }, "403": { "description": "HTTP 403; needs backoffice.inventory.transformations.view", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransformationForbidden" } } } }, "404": { "description": "HTTP 404; transformation_not_found for a missing transformation or one of another company", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/TransformationProblem" }, { "$ref": "#/components/schemas/TransformationUnauthenticated" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Backoffice - Inventory Transformations" ], "summary": "Update the header of a transformation (Transformación de ítems)", "description": "Changes the date and both locations of an open transformation at the version the client read; the version moves by 1. responsible_user_id is accepted and ignored: the Responsable changes only through PUT /{id}/responsible.", "operationId": "fec4aae1058827ddedf632ecc0d8f9d5", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "Transformation ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransformationHeaderRequest" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransformationHeaderUpdated" } } } }, "401": { "description": "HTTP 401", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransformationUnauthenticated" } } } }, "403": { "description": "HTTP 403; needs backoffice.inventory.transformations.update", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransformationForbidden" } } } }, "404": { "description": "HTTP 404; transformation_not_found for a missing transformation or one of another company", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/TransformationProblem" }, { "$ref": "#/components/schemas/TransformationUnauthenticated" } ] } } } }, "409": { "description": "HTTP 409; transformation_version_conflict when another write saved first, transformation_cannot_be_modified (with transformation_status) for a procesada or anulada transformation", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/TransformationProblem" }, { "$ref": "#/components/schemas/TransformationClosedProblem" } ] } } } }, "422": { "description": "HTTP 422; errors names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransformationProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/transformations/{id}/lines": { "put": { "tags": [ "Backoffice - Inventory Transformations" ], "summary": "Update the consumed and produced quantities of a transformation (Transformación de ítems)", "description": "Applies each line that carries a quantity at the version the client read; every changed line moves the version by 1 and an unchanged request saves nothing. The response carries no version: refetch the record.", "operationId": "73c43c669897889c89f7deb8d5203cbb", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "Transformation ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransformationLinesRequest" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransformationLinesUpdated" } } } }, "401": { "description": "HTTP 401", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransformationUnauthenticated" } } } }, "403": { "description": "HTTP 403; needs backoffice.inventory.transformations.update", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransformationForbidden" } } } }, "404": { "description": "HTTP 404; transformation_not_found for a missing transformation or one of another company", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/TransformationProblem" }, { "$ref": "#/components/schemas/TransformationUnauthenticated" } ] } } } }, "409": { "description": "HTTP 409; transformation_version_conflict when another write saved first, transformation_cannot_be_modified (with transformation_status) for a procesada or anulada transformation", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/TransformationProblem" }, { "$ref": "#/components/schemas/TransformationClosedProblem" } ] } } } }, "400": { "description": "HTTP 400; a line id the transformation does not have, or a quantity on the wrong line type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransformationProblem" } } } }, "422": { "description": "HTTP 422; errors names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransformationProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/transformations": { "get": { "tags": [ "Backoffice - Inventory Transformations" ], "summary": "List transformations (Transformación de ítems)", "description": "Values are ORed within a field and ANDed across fields. meta.counts drops only the status filter; meta.label_counts drops only label_ids. A search with no match is an empty page.", "operationId": "74b07aee20ae5a71d9bab6f05d5f9ed8", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "status[]", "in": "query", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "por_aprobar", "en_proceso", "procesada", "anulada" ] } } }, { "name": "status", "in": "query", "description": "Scalar alias of status[]; all or an empty value does not filter.", "schema": { "type": "string", "enum": [ "por_aprobar", "en_proceso", "procesada", "anulada", "all" ] } }, { "name": "input_location_id[]", "in": "query", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" } } }, { "name": "input_location_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "output_location_id[]", "in": "query", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" } } }, { "name": "output_location_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "responsible_user_id[]", "in": "query", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "pattern": "^(?:[1-9][0-9]{0,17}|[1-8][0-9]{18}|9[0-1][0-9]{17}|92[0-1][0-9]{16}|922[0-2][0-9]{15}|9223[0-2][0-9]{14}|92233[0-6][0-9]{13}|922337[0-1][0-9]{12}|92233720[0-2][0-9]{10}|922337203[0-5][0-9]{9}|9223372036[0-7][0-9]{8}|92233720368[0-4][0-9]{7}|922337203685[0-3][0-9]{6}|9223372036854[0-6][0-9]{5}|92233720368547[0-6][0-9]{4}|922337203685477[0-4][0-9]{3}|9223372036854775[0-7][0-9]{2}|922337203685477580[0-6]|9223372036854775807)$" } } }, { "name": "responsible_user_id", "in": "query", "schema": { "type": "string", "pattern": "^(?:[1-9][0-9]{0,17}|[1-8][0-9]{18}|9[0-1][0-9]{17}|92[0-1][0-9]{16}|922[0-2][0-9]{15}|9223[0-2][0-9]{14}|92233[0-6][0-9]{13}|922337[0-1][0-9]{12}|92233720[0-2][0-9]{10}|922337203[0-5][0-9]{9}|9223372036[0-7][0-9]{8}|92233720368[0-4][0-9]{7}|922337203685[0-3][0-9]{6}|9223372036854[0-6][0-9]{5}|92233720368547[0-6][0-9]{4}|922337203685477[0-4][0-9]{3}|9223372036854775[0-7][0-9]{2}|922337203685477580[0-6]|9223372036854775807)$" } }, { "name": "label_ids[]", "in": "query", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 20 } }, { "name": "label_ids", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "search", "in": "query", "description": "Matches the code, the input and output location names and the Responsable name", "schema": { "type": "string", "maxLength": 255 } }, { "name": "code", "in": "query", "schema": { "type": "string", "maxLength": 255 } }, { "name": "location_id", "in": "query", "description": "The input location; use input_location_id", "deprecated": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "date_from", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "date_to", "in": "query", "description": "Inclusive: the day itself counts. Must not be before date_from.", "schema": { "type": "string", "format": "date" } }, { "name": "sort_by", "in": "query", "schema": { "type": "string", "default": "code", "enum": [ "code", "date" ] } }, { "name": "sort_order", "in": "query", "description": "An id tie follows the same direction", "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } }, { "name": "group_by", "in": "query", "description": "Orders por_aprobar, en_proceso, procesada, anulada before paginating", "schema": { "type": "string", "enum": [ "status" ] } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 15, "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransformationsPage" } } } }, "401": { "description": "HTTP 401", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransformationUnauthenticated" } } } }, "403": { "description": "HTTP 403; needs backoffice.inventory.transformations.view", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransformationForbidden" } } } }, "422": { "description": "HTTP 422; errors names the parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransformationProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Inventory Transformations" ], "summary": "Create a transformation (Transformación de ítems)", "description": "Creates a por_aprobar transformation at version 1 with its required Responsable. Navigate with the returned id and read the code from the record.", "operationId": "6dfe2dc5c6d61278604871e4ba0bf4a3", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransformationCreateRequest" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransformationCreated" } } } }, "400": { "description": "HTTP 400; the lines break an aggregate invariant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransformationProblem" } } } }, "401": { "description": "HTTP 401", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransformationUnauthenticated" } } } }, "403": { "description": "HTTP 403; needs backoffice.inventory.transformations.create", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransformationForbidden" } } } }, "422": { "description": "HTTP 422; errors names the field: lines for a missing input or output, lines.N.expected_quantity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransformationProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/transformations/{transformationId}/process": { "put": { "tags": [ "Backoffice - Inventory Transformations" ], "summary": "Process a transformation (Transformación de ítems)", "description": "Completes the quantities, checks the input location stock under lock, values the lines in both books and marks the transformation procesada; the version moves by 2. Refusals carry a code and the data to render them.", "operationId": "cebce6be65d733342b0dc485afe7b504", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "transformationId", "in": "path", "description": "Transformation ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransformationProcessRequest" } } } }, "responses": { "200": { "description": "Processed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransformationProcessed" } } } }, "401": { "description": "HTTP 401", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransformationUnauthenticated" } } } }, "403": { "description": "HTTP 403; needs backoffice.inventory.transformations.update_status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransformationForbidden" } } } }, "404": { "description": "HTTP 404; transformation_not_found for a missing transformation or one of another company", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/TransformationProblem" }, { "$ref": "#/components/schemas/TransformationUnauthenticated" } ] } } } }, "409": { "description": "HTTP 409; transformation_version_conflict", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/TransformationProblem" }, { "$ref": "#/components/schemas/TransformationClosedProblem" } ] } } } }, "422": { "description": "HTTP 422; transformation_cannot_be_processed with transformation_status, insufficient_inventory with item_id, location_id and both quantities, accounting_configuration_incomplete, or validation", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/TransformationProblem" }, { "$ref": "#/components/schemas/TransformationCannotBeProcessedProblem" }, { "$ref": "#/components/schemas/TransformationInsufficientInventoryProblem" }, { "$ref": "#/components/schemas/TransformationAccountingConfigurationError" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/transformations/{id}/responsible": { "put": { "tags": [ "Backoffice - Inventory Transformations" ], "summary": "Reassign the Responsable of a transformation (Transformación de ítems)", "description": "Only a por_aprobar or en_proceso transformation takes a new Responsable; an unchanged value writes nothing. The version does not move, so an unsaved edit stays valid. The change is recorded in the transformation Activity.", "operationId": "fbe52b5704dced3b4793e8e73feffc3c", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "Transformation ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransformationResponsibleRequest" } } } }, "responses": { "200": { "description": "Empty JSON object acknowledgement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransformationAcknowledgement" } } } }, "401": { "description": "HTTP 401", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransformationUnauthenticated" } } } }, "403": { "description": "HTTP 403; needs backoffice.inventory.transformations.update", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransformationForbidden" } } } }, "404": { "description": "HTTP 404; transformation_not_found for a missing transformation or one of another company", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/TransformationProblem" }, { "$ref": "#/components/schemas/TransformationUnauthenticated" } ] } } } }, "409": { "description": "HTTP 409; transformation_responsible_cannot_be_reassigned for a procesada or anulada transformation, even with the same value", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransformationProblem" } } } }, "422": { "description": "HTTP 422; validation, or transformation_responsible_user_not_in_company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransformationProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/transformations/{id}/status": { "put": { "tags": [ "Backoffice - Inventory Transformations" ], "summary": "Change the status of a transformation (Transformación de ítems)", "description": "Moves an open transformation along its lifecycle at the version the client read; the version moves by 1. Starting the process checks no stock and annulling releases nothing: stock is checked only by PUT /{transformationId}/process.", "operationId": "cab198e628b5921c5d426ebba0ce8a1b", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "Transformation ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransformationStatusRequest" } } } }, "responses": { "200": { "description": "Empty JSON object acknowledgement; refetch the record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransformationAcknowledgement" } } } }, "401": { "description": "HTTP 401", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransformationUnauthenticated" } } } }, "403": { "description": "HTTP 403; needs backoffice.inventory.transformations.update_status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransformationForbidden" } } } }, "404": { "description": "HTTP 404; transformation_not_found for a missing transformation or one of another company", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/TransformationProblem" }, { "$ref": "#/components/schemas/TransformationUnauthenticated" } ] } } } }, "409": { "description": "HTTP 409; transformation_version_conflict when another write saved first, transformation_cannot_be_modified (with transformation_status) for a procesada or anulada transformation", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/TransformationProblem" }, { "$ref": "#/components/schemas/TransformationClosedProblem" } ] } } } }, "400": { "description": "HTTP 400; invalid_transformation_status_transition, or transformation_quantities_incomplete when procesada is asked with incomplete quantities", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransformationProblem" } } } }, "422": { "description": "HTTP 422; errors names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransformationProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/units/lookup": { "get": { "tags": [ "Backoffice - Inventory - Unit Lookups" ], "summary": "Lookup Units for tenant forms", "operationId": "768c8aff84e24b71e67e3f11151cfe00", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "active", "inactive" ] } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 200, "minimum": 1 } } ], "responses": { "200": { "description": "Minimal Unit projection", "content": { "application/json": { "schema": { "properties": { "items": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "inactive" ] } }, "type": "object" } }, "total": { "type": "integer" }, "per_page": { "type": "integer" }, "current_page": { "type": "integer" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Not a member of this tenant" }, "404": { "description": "Tenant not found" }, "422": { "description": "Invalid status filter" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/variant-groups/{id}/activation": { "put": { "tags": [ "Backoffice - Inventory - Variant Groups" ], "summary": "Activate a Modelo", "description": "Activates an inactive Modelo: it is offered again where a Modelo is picked. Requires backoffice.inventory.items.update.", "operationId": "cb0f6df49156663f6315e9c7d2e2b71d", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Modelo activated", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VariantGroupUnauthenticated" } } } }, "403": { "description": "Missing backoffice.inventory.items.update", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VariantGroupProblem" } } } }, "404": { "description": "variant_group_not_found from the controller (also for another company's Modelo), or the router's or middleware's message", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VariantGroupNotFound404" } } } }, "409": { "description": "variant_group_status_transition_not_allowed when it is already active; variant_group_name_already_exists or variant_group_already_exists from a concurrent save", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VariantGroupProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/variant-groups/{id}/deactivation": { "put": { "tags": [ "Backoffice - Inventory - Variant Groups" ], "summary": "Deactivate a Modelo", "description": "Deactivates an active Modelo: it keeps its Variantes and stops being offered where a Modelo is picked. Requires backoffice.inventory.items.update.", "operationId": "8f9b9356126d80c14a8d696384c32db5", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Modelo deactivated", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VariantGroupUnauthenticated" } } } }, "403": { "description": "Missing backoffice.inventory.items.update", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VariantGroupProblem" } } } }, "404": { "description": "variant_group_not_found from the controller (also for another company's Modelo), or the router's or middleware's message", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VariantGroupNotFound404" } } } }, "409": { "description": "variant_group_status_transition_not_allowed when it is already inactive; variant_group_name_already_exists or variant_group_already_exists from a concurrent save", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VariantGroupProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/variant-groups/{id}": { "get": { "tags": [ "Backoffice - Inventory - Variant Groups" ], "summary": "Show a Modelo", "description": "The Modelo with its Variantes (every Item of it, in any status, ordered by code then id, unpaged), their count and whether that locks its option names. Another company's Modelo is not found. Requires backoffice.inventory.items.view.", "operationId": "009ea1f74be8d3d89329fd404cf73c23", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Modelo found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VariantGroupDetail" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VariantGroupUnauthenticated" } } } }, "403": { "description": "Missing backoffice.inventory.items.view", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VariantGroupProblem" } } } }, "404": { "description": "variant_group_not_found from the controller, or the router's or middleware's message", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VariantGroupNotFound404" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Backoffice - Inventory - Variant Groups" ], "summary": "Edit a Modelo", "description": "Replaces the Modelo's name and option names. Once it has Variantes its option names cannot change (adding, removing, renaming, letter case or order): 409 variant_group_options_locked; its name stays editable. Requires backoffice.inventory.items.update.", "operationId": "f04091ccb167fbb307d337a2919861f6", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VariantGroupUpdateRequest" } } } }, "responses": { "200": { "description": "Modelo saved", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VariantGroupUnauthenticated" } } } }, "403": { "description": "Missing backoffice.inventory.items.update", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VariantGroupProblem" } } } }, "404": { "description": "variant_group_not_found from the controller (also for another company's Modelo), or the router's or middleware's message", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VariantGroupNotFound404" } } } }, "409": { "description": "variant_group_options_locked, variant_group_name_already_exists or variant_group_already_exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VariantGroupProblem" } } } }, "422": { "description": "Request validation (error_code null, with errors by field), invalid_variant_group_name, invalid_variant_group_option_count, invalid_variant_group_option_name or duplicate_variant_group_option_name", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VariantGroupProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/inventory/variant-groups": { "get": { "tags": [ "Backoffice - Inventory - Variant Groups" ], "summary": "List Modelos", "description": "A page of the company's Modelos, each with its Variante count. meta.counts holds both statuses under the same search, whatever the status filter. Empty values count as omitted. Requires backoffice.inventory.items.view.", "operationId": "52737320efc2d46561eaf6c1e56b96e4", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "search", "in": "query", "description": "Matches the name literally, ignoring letter case and accents; trimmed.", "required": false, "schema": { "type": "string" } }, { "name": "status[]", "in": "query", "description": "Statuses to list; all, or no status, lists every one. A scalar status is accepted.", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "active", "inactive", "all" ] } } }, { "name": "sort_by", "in": "query", "description": "Ties are ordered by id in the same direction. Any other field answers 422 invalid_list_sort.", "required": false, "schema": { "type": "string", "default": "name", "enum": [ "name", "created_at" ] } }, { "name": "sort_order", "in": "query", "description": "Any other direction answers 422 invalid_list_sort.", "required": false, "schema": { "type": "string", "default": "asc", "enum": [ "asc", "desc" ] } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "Modelos found; a company without Modelos lists none with both counts at 0", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VariantGroupList" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VariantGroupUnauthenticated" } } } }, "403": { "description": "Missing backoffice.inventory.items.view", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VariantGroupProblem" } } } }, "404": { "description": "The middleware's message for an unknown company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VariantGroupMiddlewareNotFound" } } } }, "422": { "description": "Query validation (error_code null, with errors by parameter) or invalid_list_sort (with errors.sort_by or errors.sort_order)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VariantGroupProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Inventory - Variant Groups" ], "summary": "Create a Modelo", "description": "Creates an active Modelo with its 1 to 3 option names. The client sends the id and reads the Modelo back with GET. Requires backoffice.inventory.items.update.", "operationId": "6c4a518025338e120ec93249ce91ba29", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VariantGroupCreateRequest" } } } }, "responses": { "201": { "description": "Modelo created", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VariantGroupUnauthenticated" } } } }, "403": { "description": "Missing backoffice.inventory.items.update", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VariantGroupProblem" } } } }, "404": { "description": "The middleware's message for an unknown company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VariantGroupMiddlewareNotFound" } } } }, "409": { "description": "variant_group_name_already_exists or variant_group_already_exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VariantGroupProblem" } } } }, "422": { "description": "Request validation (error_code null, with errors by field), invalid_variant_group_name, invalid_variant_group_option_count, invalid_variant_group_option_name or duplicate_variant_group_option_name", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VariantGroupProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/menu/menu-contexts": { "get": { "tags": [ "Backoffice - Menu - Contexts" ], "summary": "Get contexts accessible to the authenticated user", "description": "Returns only contexts whose declared menu tree contains a leaf for which the user holds the exact 'backoffice.{context_id}.{module_path}.view' permission. A user who holds a super-admin role in this company (the {tenant} path parameter) bypasses filtering and receives all contexts; being super admin of another company bypasses nothing.", "operationId": "4cd01540ca46afd589e1209f1e172705", "parameters": [ { "name": "tenant", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful retrieval of accessible contexts list", "content": { "application/json": { "schema": { "properties": { "contexts": { "type": "array", "items": { "properties": { "id": { "type": "string", "example": "accounting" }, "name": { "type": "string", "example": "Accounting" } }, "type": "object" } } }, "type": "object" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unauthorized" }, "status": { "type": "integer", "example": 403 }, "detail": { "type": "string", "example": "You do not have permission to view this resource." } }, "type": "object" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Internal Server Error" }, "detail": { "type": "string", "example": "An unexpected error occurred" }, "status": { "type": "integer", "example": 500 } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/menu/menu-modules": { "get": { "tags": [ "Backoffice - Menu - Modules" ], "summary": "Get modules for a specific context", "description": "Returns modules the authenticated user can view within the specified context. The context_id is either a vertical listed by menu-contexts or 'company', the company settings area, which is never listed as a context. A leaf requires its exact 'backoffice.{context_id}.{module_path}.view' permission, unless it declares the permission of the page it opens: every 'company' section does (Etiquetas requires 'backoffice.companies.labels.manage'). Declared permissions are never returned. A parent is included with only its viewable children. A user who holds a super-admin role in this company (the {tenant} path parameter) bypasses filtering and receives all modules; being super admin of another company bypasses nothing. An unknown context returns an empty list.", "operationId": "b1496631d5cff520cd1a23e2547293a8", "parameters": [ { "name": "tenant", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string" } }, { "name": "context_id", "in": "query", "description": "The area to get modules for: a vertical listed by menu-contexts (e.g. 'sales' or 'inventory') or 'company', the company settings area.", "required": true, "schema": { "type": "string", "example": "company" } } ], "responses": { "200": { "description": "Successful retrieval of modules list", "content": { "application/json": { "schema": { "properties": { "modules": { "type": "array", "items": { "required": [ "id", "name" ], "properties": { "id": { "type": "string", "example": "settings" }, "name": { "type": "string", "example": "Configuración de la compañía" }, "children": { "description": "Present only on a parent module: its viewable sections, in display order.", "type": "array", "items": { "required": [ "id", "name" ], "properties": { "id": { "type": "string", "example": "labels" }, "name": { "type": "string", "example": "Etiquetas" } }, "type": "object" } } }, "type": "object" } } }, "type": "object" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Bad Request" }, "status": { "type": "integer", "example": 400 }, "detail": { "type": "string", "example": "Context ID is required" } }, "type": "object" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unauthorized" }, "status": { "type": "integer", "example": 403 }, "detail": { "type": "string", "example": "You do not have permission to view this resource." } }, "type": "object" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Internal Server Error" }, "detail": { "type": "string", "example": "An unexpected error occurred" }, "status": { "type": "integer", "example": 500 } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/contract-activations/{id}/approve": { "post": { "tags": [ "Backoffice - Purchase Contract Activations" ], "summary": "Approve a Purchase Contract Activation", "operationId": "ee022a2957a1ffce72113ca16578475d", "parameters": [ { "name": "tenant", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "Purchase Contract Activation identifier", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "financial_fingerprint": { "description": "Required when stored header amounts differ from the recalculation.", "type": "string", "pattern": "^[a-f0-9]{64}$", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Purchase Contract Activation approved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractActivationLifecycleResponse" } } } }, "403": { "description": "Missing approve permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractActivationMiddlewareError" } } } }, "404": { "description": "Activation or Purchase Contract not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractActivationProblem" } } } }, "409": { "description": "Only to_approve activations can be approved, the Purchase Contract is not active, or the contract already has an active activation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractActivationProblem" } } } }, "422": { "description": "Historical fingerprint required/stale or unit_price mismatch", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractActivationValidationError" }, { "$ref": "#/components/schemas/PurchaseContractActivationProblem" } ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractActivationMiddlewareError" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/contract-activations/{id}/cancel": { "post": { "tags": [ "Backoffice - Purchase Contract Activations" ], "summary": "Cancel a Purchase Contract Activation", "operationId": "d18440b3edb408dee091e33b32af963e", "parameters": [ { "name": "tenant", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "Purchase Contract Activation identifier", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Purchase Contract Activation cancelled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractActivationLifecycleResponse" } } } }, "403": { "description": "Missing cancel permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractActivationMiddlewareError" } } } }, "404": { "description": "Activation or Purchase Contract not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractActivationProblem" } } } }, "409": { "description": "Only to_approve or active activations can be cancelled, or the Purchase Contract is not active", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractActivationProblem" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractActivationMiddlewareError" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/contract-activations/{id}": { "get": { "tags": [ "Backoffice - Purchase Contract Activations" ], "summary": "Find a Purchase Contract Activation", "operationId": "88eab84535021931c2c8f81c8721c633", "parameters": [ { "name": "tenant", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "Purchase Contract Activation identifier", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Purchase Contract Activation detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractActivationResource" } } } }, "403": { "description": "Missing view permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractActivationMiddlewareError" } } } }, "404": { "description": "Purchase Contract Activation not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractActivationProblem" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractActivationMiddlewareError" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Backoffice - Purchase Contract Activations" ], "summary": "Update a to_approve Purchase Contract Activation", "operationId": "38de520139892d4a8363bb2f7a02eeef", "parameters": [ { "name": "tenant", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "Purchase Contract Activation identifier", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractActivationUpdateRequest" } } } }, "responses": { "200": { "description": "Purchase Contract Activation updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractActivationMutationResponse" } } } }, "403": { "description": "Missing update permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractActivationMiddlewareError" } } } }, "404": { "description": "Activation, Purchase Contract, or referenced line not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractActivationProblem" } } } }, "409": { "description": "Activation lifecycle conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractActivationProblem" } } } }, "422": { "description": "Malformed input, unit_price present on write, calculated totals over storage limit, preview mismatch, or tax selection invalid", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractActivationValidationError" }, { "$ref": "#/components/schemas/PurchaseContractActivationProblem" } ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractActivationMiddlewareError" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/contract-activations": { "get": { "tags": [ "Backoffice - Purchase Contract Activations" ], "summary": "Search Purchase Contract Activations", "operationId": "937481e213c9339e4a2a3f249dcf9448", "parameters": [ { "name": "tenant", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "purchase_contract_id", "in": "query", "description": "Single value; use purchase_contract_id[] for multiple values", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "purchase_contract_id[]", "in": "query", "description": "Matches any supplied value (OR); different filters intersect (AND)", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" } } }, { "name": "provider_id", "in": "query", "description": "Single value; use provider_id[] for multiple values", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "provider_id[]", "in": "query", "description": "Matches any supplied value (OR); different filters intersect (AND)", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" } } }, { "name": "status", "in": "query", "description": "Single value; use status[] for multiple values", "required": false, "schema": { "type": "string", "enum": [ "to_approve", "active", "cancelled", "ended" ] } }, { "name": "status[]", "in": "query", "description": "Matches any supplied value (OR); different filters intersect (AND)", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "to_approve", "active", "cancelled", "ended" ] } } }, { "name": "purchase_contract_activation_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "label_ids", "in": "query", "description": "Single value; use label_ids[] for multiple values", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "label_ids[]", "in": "query", "description": "Matches any supplied value (OR); different filters intersect (AND)", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 20 } }, { "name": "sort_by", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "activation_date", "start_date", "code" ] } }, { "name": "sort_order", "in": "query", "required": false, "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } }, { "name": "date_from", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "date_to", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "search_query", "in": "query", "description": "Matches activation code", "required": false, "schema": { "type": "string", "maxLength": 255 } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "Paginated Purchase Contract Activations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractActivationsPage" } } } }, "403": { "description": "Missing view permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractActivationMiddlewareError" } } } }, "422": { "description": "Malformed search criteria", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractActivationValidationError" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractActivationMiddlewareError" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Purchase Contract Activations" ], "summary": "Create a Purchase Contract Activation", "operationId": "5a5616f707c30de2c69f6bdde449165b", "parameters": [ { "name": "tenant", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractActivationCreateRequest" } } } }, "responses": { "201": { "description": "Purchase Contract Activation created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractActivationMutationResponse" } } } }, "403": { "description": "Missing create permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractActivationMiddlewareError" } } } }, "404": { "description": "Purchase Contract or referenced line not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractActivationProblem" } } } }, "409": { "description": "Activation ID or generated code conflicts with existing data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractActivationProblem" } } } }, "422": { "description": "Malformed input, unit_price present on write, calculated totals over storage limit, preview mismatch, or tax selection invalid", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractActivationValidationError" }, { "$ref": "#/components/schemas/PurchaseContractActivationProblem" } ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractActivationMiddlewareError" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/contract-activations/source-contract/{id}": { "get": { "tags": [ "Backoffice - Purchase Contract Activations" ], "summary": "Only the contract facts used to prepare an activation", "operationId": "37b08196555654b1ad7e2541a8c30aac", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Activation source", "content": { "application/json": { "schema": { "required": [ "id", "code", "provider_id", "provider_name", "status", "start_date", "due_date", "items" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "provider_id": { "type": "string", "format": "uuid" }, "provider_name": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "pending_approval", "active", "cancelled" ] }, "start_date": { "type": "string", "format": "date" }, "due_date": { "type": "string", "format": "date" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/PurchaseContractItem" } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Activation view, create or update permission required" }, "404": { "description": "Contract not found in this company" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/contract-addenda": { "get": { "tags": [ "Backoffice - Purchase Contract Addenda" ], "summary": "Search Purchase Contract Addenda", "operationId": "c88ecb680b62d955e95bd066b567e8ff", "parameters": [ { "name": "tenant", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "purchase_contract_id", "in": "query", "description": "Single value; use purchase_contract_id[] for multiple values", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "purchase_contract_id[]", "in": "query", "description": "Flat array; OR within field", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" } } }, { "name": "provider_id", "in": "query", "description": "Single value; use provider_id[] for multiple values", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "provider_id[]", "in": "query", "description": "Flat array; OR within field", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" } } }, { "name": "status", "in": "query", "description": "Single value; use status[] for multiple values", "required": false, "schema": { "type": "string", "enum": [ "to_approve", "approved", "cancelled" ] } }, { "name": "status[]", "in": "query", "description": "Flat array; OR within field", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "to_approve", "approved", "cancelled" ] } } }, { "name": "purchase_contract_activation_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "label_ids", "in": "query", "description": "Single value; use label_ids[] for multiple values", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "label_ids[]", "in": "query", "description": "Flat array; OR within field", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 20 } }, { "name": "sort_by", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "effective_date", "code" ] } }, { "name": "sort_order", "in": "query", "required": false, "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } }, { "name": "date_from", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "date_to", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "search_query", "in": "query", "description": "Matches Addendum code", "required": false, "schema": { "type": "string", "maxLength": 255 } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "Page", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractAddendaPage" } } } }, "403": { "description": "Missing view permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractAddendumProblem" } } } }, "422": { "description": "Malformed search criteria", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractAddendumValidationError" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractAddendumMiddlewareError" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Purchase Contract Addenda" ], "summary": "Open a Purchase Contract Addendum against the active Activation", "operationId": "431b34084f3375160dd826f53aef8c93", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractAddendumCreateRequest" } } } }, "responses": { "201": { "description": "Purchase Contract Addendum created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractAddendumMutationResponse" } } } }, "403": { "description": "Missing create permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractAddendumProblem" } } } }, "404": { "description": "Activation or Purchase Contract not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractAddendumProblem" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractAddendumProblem" } } } }, "422": { "description": "Validation error; preview mismatch (purchase_contract_addendum_preview_mismatch)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractAddendumProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/contract-addenda/{id}/approve": { "post": { "tags": [ "Backoffice - Purchase Contract Addenda" ], "summary": "Approve a Purchase Contract Addendum, settling old terms then rewriting lines", "operationId": "b7cc1eeaf8bcd74ea1e288af4d47e1d2", "parameters": [ { "name": "tenant", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "Purchase Contract Addendum identifier", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "financial_fingerprint": { "description": "Required when stored line commercial facts differ from the recalculation.", "type": "string", "pattern": "^[a-f0-9]{64}$", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Addendum approved; Activation stays active with rewritten lines", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractAddendumApprovalResponse" } } } }, "403": { "description": "Missing approve permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractAddendumProblem" } } } }, "404": { "description": "Addendum, Activation or Purchase Contract not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractAddendumProblem" } } } }, "409": { "description": "Lifecycle conflict including a pending sibling document on the contract, effective date not in the future, blocked settlement, open charge on or after the effective date, or divergent shared contract lines", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractAddendumProblem" } } } }, "422": { "description": "Addendum missing an activation line (coverage corruption); or historical difference acceptance required/stale", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractAddendumProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/contract-addenda/{id}": { "get": { "tags": [ "Backoffice - Purchase Contract Addenda" ], "summary": "Find a Purchase Contract Addendum", "operationId": "8ea4165df7c4e69b06b997bb558af3d2", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractAddendumResource" } } } }, "403": { "description": "Missing view permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractAddendumProblem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractAddendumProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Backoffice - Purchase Contract Addenda" ], "summary": "Update a to_approve Purchase Contract Addendum", "operationId": "3ddd669701810e77727f3ffb1434e1fd", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractAddendumUpdateRequest" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractAddendumMutationResponse" } } } }, "403": { "description": "Missing update permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractAddendumProblem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractAddendumProblem" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractAddendumProblem" } } } }, "422": { "description": "Validation error; preview mismatch (purchase_contract_addendum_preview_mismatch)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractAddendumProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Backoffice - Purchase Contract Addenda" ], "summary": "Delete a to_approve Purchase Contract Addendum", "operationId": "a2734796501af7a2e224de9aeb10524b", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Deleted" }, "403": { "description": "Missing delete permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractAddendumProblem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractAddendumProblem" } } } }, "409": { "description": "Not deletable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractAddendumProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/contract-addenda/source-activation/{id}": { "get": { "tags": [ "Backoffice - Purchases - ContractAddenda" ], "summary": "Only the active source facts this child document needs", "operationId": "05722af1aa2367c92636e86980f23ebf", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Child-owned active source projection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractAddendumSource" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "This child module view, create or update permission required" }, "404": { "description": "Active source and parent not found in this company" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/contract-charges/{id}": { "get": { "tags": [ "Backoffice - Purchase Contract Charges" ], "summary": "Find a Purchase Contract Charge", "operationId": "beba966706f9deb07899419b62a98f46", "parameters": [ { "name": "tenant", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "Purchase Contract Charge identifier", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Purchase Contract Charge detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractChargeResource" } } } }, "403": { "description": "Missing view permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractChargeProblem" } } } }, "404": { "description": "Purchase Contract Charge not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractChargeProblem" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractChargeMessageProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/contract-charges": { "get": { "tags": [ "Backoffice - Purchase Contract Charges" ], "summary": "Search Purchase Contract Charges", "operationId": "78d01e1defa6389be59fc2952e126571", "parameters": [ { "name": "tenant", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "purchase_contract_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "purchase_contract_id[]", "in": "query", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" } } }, { "name": "purchase_contract_activation_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "provider_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "provider_id[]", "in": "query", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" } } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "to_be_invoiced", "invoiced", "cancelled" ] } }, { "name": "status[]", "in": "query", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "to_be_invoiced", "invoiced", "cancelled" ] } } }, { "name": "sort_by", "in": "query", "required": false, "schema": { "type": "string", "default": "charge_date", "enum": [ "charge_date", "code" ] } }, { "name": "sort_order", "in": "query", "required": false, "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } }, { "name": "date_from", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "date_to", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "search_query", "in": "query", "description": "Matches charge code or item name", "required": false, "schema": { "type": "string", "maxLength": 255 } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "Paginated Purchase Contract Charges", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractChargesPage" } } } }, "403": { "description": "Missing view permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractChargeProblem" } } } }, "422": { "description": "Malformed search criteria", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractChargeValidationProblem" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractChargeMessageProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/contract-deactivations/{id}/approve": { "post": { "tags": [ "Backoffice - Purchase Contract Deactivations" ], "summary": "Approve a Purchase Contract Deactivation, settling its Charges through the inclusive cutoff", "operationId": "e9a3af485e62783b772020578381892e", "parameters": [ { "name": "tenant", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "Purchase Contract Deactivation identifier", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "financial_fingerprint": { "description": "Required when stored header amounts differ from the recalculation.", "type": "string", "pattern": "^[a-f0-9]{64}$", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Deactivation approved, Activation ended and Charges settled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractDeactivationApprovalResponse" } } } }, "403": { "description": "Missing approve permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractDeactivationProblem" } } } }, "404": { "description": "Deactivation, Activation or Purchase Contract not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractDeactivationProblem" } } } }, "409": { "description": "purchase_contract_not_active; purchase_contract_deactivation_cannot_be_approved; purchase_contract_activation_cannot_be_ended; effective_deactivation_date_in_future; purchase_contract_deactivation_lifecycle_changed; purchase_contract_deactivation_charge_settlement_failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractDeactivationProblem" } } } }, "422": { "description": "effective_deactivation_date_before_billing_start uses error_code; historical required/stale use error; malformed input uses native validation", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractDeactivationProblem" }, { "$ref": "#/components/schemas/PurchaseContractDeactivationHistoricalDifferenceProblem" }, { "$ref": "#/components/schemas/PurchaseContractDeactivationValidationProblem" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/contract-deactivations/{id}": { "get": { "tags": [ "Backoffice - Purchase Contract Deactivations" ], "summary": "Find a Purchase Contract Deactivation", "operationId": "8b5e4469575231e79a5832f0f19615b3", "parameters": [ { "name": "tenant", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "Purchase Contract Deactivation identifier", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Purchase Contract Deactivation detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractDeactivationResource" } } } }, "403": { "description": "Missing view permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractDeactivationProblem" } } } }, "404": { "description": "Purchase Contract Deactivation not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractDeactivationProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Backoffice - Purchase Contract Deactivations" ], "summary": "Update the terms of a to_approve Purchase Contract Deactivation", "operationId": "57b886c269e6f2c81088e784f782efc2", "parameters": [ { "name": "tenant", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "Purchase Contract Deactivation identifier", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractDeactivationUpdateRequest" } } } }, "responses": { "200": { "description": "Purchase Contract Deactivation updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractDeactivationMutationResponse" } } } }, "403": { "description": "Missing update permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractDeactivationProblem" } } } }, "404": { "description": "Deactivation, Activation or Purchase Contract not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractDeactivationProblem" } } } }, "409": { "description": "Only to_approve deactivations can be updated, the Purchase Contract is not active, or the deactivation changed while it was being written", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractDeactivationProblem" } } } }, "422": { "description": "Malformed input, id/activation/items supplied on update, or effective date before the activation billing start", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractDeactivationProblem" }, { "$ref": "#/components/schemas/PurchaseContractDeactivationValidationProblem" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Backoffice - Purchase Contract Deactivations" ], "summary": "Delete a to_approve Purchase Contract Deactivation", "operationId": "4a9af333e73403d33047b88ddaf090a0", "parameters": [ { "name": "tenant", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "Purchase Contract Deactivation identifier", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Purchase Contract Deactivation deleted" }, "403": { "description": "Missing delete permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractDeactivationProblem" } } } }, "404": { "description": "Purchase Contract Deactivation not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractDeactivationProblem" } } } }, "409": { "description": "Only to_approve deactivations can be deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractDeactivationProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/contract-deactivations": { "get": { "tags": [ "Backoffice - Purchase Contract Deactivations" ], "summary": "Search Purchase Contract Deactivations", "operationId": "4c3b36060e32d0e322d796d8140ff8d1", "parameters": [ { "name": "tenant", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "purchase_contract_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "purchase_contract_activation_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "provider_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "to_approve", "approved", "cancelled" ] } }, { "name": "purchase_contract_id[]", "in": "query", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" } } }, { "name": "provider_id[]", "in": "query", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" } } }, { "name": "status[]", "in": "query", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "to_approve", "approved", "cancelled" ] } } }, { "name": "label_ids", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "label_ids[]", "in": "query", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 20 } }, { "name": "sort_by", "in": "query", "required": false, "schema": { "type": "string", "default": "code", "enum": [ "effective_deactivation_date", "code" ] } }, { "name": "sort_order", "in": "query", "required": false, "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } }, { "name": "date_from", "in": "query", "description": "Lower bound on effective_deactivation_date", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "date_to", "in": "query", "description": "Upper bound on effective_deactivation_date", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "search_query", "in": "query", "description": "Matches deactivation code", "required": false, "schema": { "type": "string", "maxLength": 255 } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "Paginated Purchase Contract Deactivations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractDeactivationsPage" } } } }, "403": { "description": "Missing view permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractDeactivationProblem" } } } }, "422": { "description": "Malformed search criteria", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractDeactivationValidationProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Purchase Contract Deactivations" ], "summary": "Open a Purchase Contract Deactivation against the active Activation", "operationId": "6bc4dc1e80463e64fe63a2c19730cd64", "parameters": [ { "name": "tenant", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractDeactivationCreateRequest" } } } }, "responses": { "201": { "description": "Purchase Contract Deactivation created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractDeactivationMutationResponse" } } } }, "403": { "description": "Missing create permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractDeactivationProblem" } } } }, "404": { "description": "Activation or Purchase Contract not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractDeactivationProblem" } } } }, "409": { "description": "Deactivation ID or code conflicts, the Activation already has a pending Deactivation, a pending sibling lifecycle document on the contract, or the Activation/Contract is not active", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractDeactivationProblem" } } } }, "422": { "description": "Malformed input, items supplied on write, effective date before the activation billing start, or calculated totals over storage limit", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractDeactivationProblem" }, { "$ref": "#/components/schemas/PurchaseContractDeactivationValidationProblem" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/contract-deactivations/source-activation/{id}": { "get": { "tags": [ "Backoffice - Purchases - ContractDeactivations" ], "summary": "Only the active source facts this child document needs", "operationId": "3d65f5838c9be67c18c7e2edef49f989", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Child-owned active source projection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractDeactivationSource" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "This child module view, create or update permission required" }, "404": { "description": "Active source and parent not found in this company" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/contracts/{id}/approve": { "post": { "tags": [ "Backoffice - Purchase Contracts" ], "summary": "Approve a Purchase Contract", "operationId": "d0b5394b807fe611f15abc672e665d3a", "parameters": [ { "name": "tenant", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "Purchase Contract identifier", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "financial_fingerprint": { "description": "Required when stored header amounts differ from the recalculation.", "type": "string", "pattern": "^[a-f0-9]{64}$", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Purchase Contract approved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractStatusResponse" } } } }, "403": { "description": "Missing approve permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } } } }, "404": { "description": "Contract, provider, or referenced resource not found", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } ] } } } }, "409": { "description": "Only pending Purchase Contracts can be approved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractProblem" } } } }, "422": { "description": "Inactive provider/account, invalid account type, a stored line whose category is not its item's or whose unit its item does not have (purchase_line_item_mismatch, with `errors` keyed by every refused line field, items.N.category_id or items.N.unit_id, N being the line's position in the `items` the contract reads with), or historical difference acceptance required/stale (purchase_contract_historical_difference_acceptance_required / purchase_contract_historical_difference_acceptance_stale)", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractValidationError" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/contracts/{id}/automation-level": { "post": { "tags": [ "Backoffice - Purchase Contracts" ], "summary": "Change a Purchase Contract's automation level and payment defaults", "description": "ADR 0081's kill switch. The only mutation an active Purchase Contract accepts, so a misbehaving automation can be stopped without cancelling the contract.", "operationId": "86371da578406f2f0d2acefd1d14755b", "parameters": [ { "name": "tenant", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "Purchase Contract identifier", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractAutomationLevelRequest" } } } }, "responses": { "200": { "description": "Automation level updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractAutomationLevelResponse" } } } }, "403": { "description": "Missing backoffice.purchases.contracts.automation.update permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } } } }, "404": { "description": "Purchase Contract not found (purchase_contract_not_found), or a payment instrument the Company does not have (purchase_contract_payment_instrument_not_found)", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } ] } } } }, "409": { "description": "Only pending or active Purchase Contracts can change their automation (purchase_contract_cannot_change_automation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractProblem" } } } }, "422": { "description": "Payment automation without invoice automation (invalid_purchase_contract_automation_level), or without a payment instrument (incomplete_purchase_contract_payment_defaults), or, while generated_payment_final_status is not none, a method reference email with an instrument that is not a crypto wallet (purchase_contract_method_reference_requires_crypto_wallet)", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractValidationError" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/contracts/{id}/cancel": { "post": { "tags": [ "Backoffice - Purchase Contracts" ], "summary": "Cancel a Purchase Contract", "operationId": "1db3e3a90addd8dd04e4e52c5fc1afc2", "parameters": [ { "name": "tenant", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "Purchase Contract identifier", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Purchase Contract cancelled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractStatusResponse" } } } }, "403": { "description": "Missing cancel permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } } } }, "404": { "description": "Purchase Contract not found", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } ] } } } }, "409": { "description": "Only active Purchase Contracts can be cancelled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/contracts/{id}": { "get": { "tags": [ "Backoffice - Purchase Contracts" ], "summary": "Find a Purchase Contract", "operationId": "6cd9c35ed80491dc7729b29905181579", "parameters": [ { "name": "tenant", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "Purchase Contract identifier", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Purchase Contract detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractResource" } } } }, "403": { "description": "Missing view permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } } } }, "404": { "description": "Purchase Contract not found", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Backoffice - Purchase Contracts" ], "summary": "Update a pending Purchase Contract", "operationId": "d2c56b90b92249d9d00ea6fe3abc23f9", "parameters": [ { "name": "tenant", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "Purchase Contract identifier", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractWriteRequest" } } } }, "responses": { "200": { "description": "Purchase Contract updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractMutationResponse" } } } }, "403": { "description": "Missing update permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } } } }, "404": { "description": "Contract, provider, or referenced resource not found, or a payment instrument the Company does not have (purchase_contract_payment_instrument_not_found)", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } ] } } } }, "409": { "description": "Contract lifecycle or duplicate line ID conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractProblem" } } } }, "422": { "description": "Malformed input; observations over 16,000 UTF-8 characters (purchase_contract_observations_too_long); calculated subtotal, discount, taxes, or total over 9999999999999.99 (purchase_contract_calculated_total_exceeds_storage_limit); preview mismatch (purchase_contract_preview_mismatch); tax selection invalid (purchase_contract_tax_selection_invalid); inactive provider/account; invalid account type; a line whose category is not its item's or whose unit its item does not have (purchase_line_item_mismatch, with `errors` keyed by every refused line field, items.N.category_id or items.N.unit_id, N being the line's position in the request's `items`); line ownership mismatch; an invalid automation level (invalid_purchase_contract_automation_level); a payment automation without a payment instrument (incomplete_purchase_contract_payment_defaults); or, while generated_payment_final_status is not none, a method reference email with an instrument that is not a crypto wallet (purchase_contract_method_reference_requires_crypto_wallet)", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractValidationError" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Backoffice - Purchase Contracts" ], "summary": "Delete a pending Purchase Contract", "operationId": "c58e6f84ca48b281e23488d37c0fc1fe", "parameters": [ { "name": "tenant", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "Purchase Contract identifier", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Purchase Contract deleted" }, "403": { "description": "Missing delete permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } } } }, "404": { "description": "Purchase Contract not found", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } ] } } } }, "409": { "description": "Only pending Purchase Contracts can be deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/contracts": { "get": { "tags": [ "Backoffice - Purchase Contracts" ], "summary": "Search Purchase Contracts", "operationId": "55c6edf9f5160be148a9c5d15e27476d", "parameters": [ { "name": "tenant", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "provider_id", "in": "query", "required": false, "schema": { "oneOf": [ { "type": "string", "format": "uuid" }, { "type": "array", "items": { "type": "string", "format": "uuid" } } ] } }, { "name": "status", "in": "query", "required": false, "schema": { "oneOf": [ { "type": "string", "enum": [ "pending_approval", "active", "cancelled" ] }, { "type": "array", "items": { "type": "string", "enum": [ "pending_approval", "active", "cancelled" ] } } ] } }, { "name": "recurring_billing", "in": "query", "required": false, "schema": { "oneOf": [ { "type": "string", "enum": [ "daily", "semi_monthly", "monthly", "annually" ] }, { "type": "array", "items": { "type": "string", "enum": [ "daily", "semi_monthly", "monthly", "annually" ] } } ] } }, { "name": "responsible_user_id", "in": "query", "required": false, "schema": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "array", "items": { "type": "string", "minLength": 1 } } ] } }, { "name": "label_ids", "in": "query", "required": false, "schema": { "oneOf": [ { "type": "string", "format": "uuid" }, { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 20 } ] } }, { "name": "sort_by", "in": "query", "required": false, "schema": { "type": "string", "default": "code", "enum": [ "start_date", "due_date", "code", "created_at" ] } }, { "name": "sort_order", "in": "query", "required": false, "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } }, { "name": "date_from", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "date_to", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "search_query", "in": "query", "description": "Matches contract code or reference", "required": false, "schema": { "type": "string", "maxLength": 255 } }, { "name": "automation_blocked", "in": "query", "description": "Filter to contracts with (true) or without (false) an unresolved automation block at ANY stage", "required": false, "schema": { "type": "string", "enum": [ "true", "false", "1", "0" ] } }, { "name": "automation_block_stage", "in": "query", "description": "Narrows automation_blocked to a single stage", "required": false, "schema": { "type": "string", "enum": [ "charge_generation", "invoicing", "invoice_approval", "payment" ] } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "Paginated Purchase Contracts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractsPage" } } } }, "403": { "description": "Missing view permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } } } }, "422": { "description": "Malformed search criteria", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractValidationError" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Purchase Contracts" ], "summary": "Create a Purchase Contract", "operationId": "4c14c4aceba04856499cca687d407d13", "parameters": [ { "name": "tenant", "in": "path", "description": "Tenant identifier", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractCreateRequest" } } } }, "responses": { "201": { "description": "Purchase Contract created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractMutationResponse" } } } }, "403": { "description": "Missing create permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } } } }, "404": { "description": "Provider or referenced resource not found, or a payment instrument the Company does not have (purchase_contract_payment_instrument_not_found)", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } ] } } } }, "409": { "description": "Contract ID, generated code, or line ID conflicts with existing data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractProblem" } } } }, "422": { "description": "Malformed input; observations over 16,000 UTF-8 characters (purchase_contract_observations_too_long); calculated subtotal, discount, taxes, or total over 9999999999999.99 (purchase_contract_calculated_total_exceeds_storage_limit); preview mismatch (purchase_contract_preview_mismatch); tax selection invalid (purchase_contract_tax_selection_invalid); inactive provider/account; invalid account type; a line whose category is not its item's or whose unit its item does not have (purchase_line_item_mismatch, with `errors` keyed by every refused line field, items.N.category_id or items.N.unit_id, N being the line's position in the request's `items`); line ownership mismatch; an invalid automation level (invalid_purchase_contract_automation_level); a payment automation without a payment instrument (incomplete_purchase_contract_payment_defaults); or, while generated_payment_final_status is not none, a method reference email with an instrument that is not a crypto wallet (purchase_contract_method_reference_requires_crypto_wallet)", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractValidationError" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/contracts/{id}/responsible": { "put": { "tags": [ "Backoffice - Purchase Contracts" ], "summary": "Reassign or clear Responsable", "operationId": "96650ed9b206380475f7d258b982cdfa", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "responsible_user_id" ], "properties": { "responsible_user_id": { "type": "string", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Changed or allowed no-op; JSON null" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } } } }, "403": { "description": "Missing UPDATE permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } } } }, "404": { "description": "Absent or foreign contract", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractProblem" }, { "$ref": "#/components/schemas/PurchaseContractMiddlewareError" } ] } } } }, "409": { "description": "Cancelled: purchase_contract_responsible_cannot_be_reassigned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseContractProblem" } } } }, "422": { "description": "Invalid input or company membership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseContractValidationError" }, { "$ref": "#/components/schemas/PurchaseContractProblem" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/credit-applications": { "get": { "tags": [ "Backoffice - Purchases Credit Applications" ], "summary": "List the applications of a supplier advance", "description": "Every application of the advance, live and reverted, by date then the order they were recorded, each as applying it answered (MER-3276). An advance applies to a bounded number of documents, so the list is not paginated; an advance of another company lists nothing. Requires backoffice.purchases.payments.view.", "operationId": "listSupplierCreditApplications", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "source_type", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "payment", "credit_note" ] } }, { "name": "source_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The advance's applications, empty when it has none", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupplierCreditApplicationList" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentMiddlewareError" } } } }, "403": { "description": "The user lacks backoffice.purchases.payments.view" }, "422": { "description": "Validation (errors)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupplierCreditApplicationProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Purchases Credit Applications" ], "summary": "Apply a supplier advance to a payable document", "description": "Applies units of a paid-out supplier advance (a payment of kind advance) to one open payable document of the same provider and company: a purchases invoice, an opening document or a supplier debit note, to be paid or partially paid (MER-3276, ADR 0215). The units, in the advance's currency, derive the debt they settle at the Rate Snapshot of the application date by the cash-event rule: today takes the official rate known now (a stale one answers the readiness envelope with OFFICIAL_RATE_STALE), an earlier date the rate of its value date (OFFICIAL_RATE_NOT_AVAILABLE when none), a later one is refused (cash_event_date_in_the_future); money kept in both books converts nothing. Within one cent of the document's open balance the debt settles it in full with the cents as a rounding difference; beyond it, 422 application_exceeds_open_balance. The document gives up the debt proportionally in its three books, the advance its proportional Carrying Amount, and each book's differences post by leg and cause on the application's entry (purchase_credit.applied), linked to the application. Applying several documents means one request per document with distinct ids; the advance is locked, so a request whose units exceed what it still holds answers 409 credit_balance_exceeded. The client generates the UUID id: resending it with the same source, target, units and date answers 200 with the application as stored, without writes; with anything else, or an id another company holds, 409 supplier_credit_application_id_conflict. Requires backoffice.purchases.payments.apply-credit.", "operationId": "applySupplierAdvance", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "id", "source", "target", "source_units", "date" ], "properties": { "id": { "type": "string", "format": "uuid" }, "source": { "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "payment", "credit_note" ] }, "id": { "description": "A paid-out supplier advance of the company; a missing or foreign one answers 422 payment_not_found.", "type": "string", "format": "uuid" } }, "type": "object" }, "target": { "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "purchases_invoice" ] }, "id": { "description": "A payable document of the company; a missing or foreign one, or a supplier credit note, answers 422 purchases_invoice_not_found.", "type": "string", "format": "uuid" } }, "type": "object" }, "source_units": { "description": "Greater than zero, at most two decimals, in the advance's currency.", "type": "string", "pattern": "^(?!0+(?:\\.0{1,2})?$)\\d{1,13}(?:\\.\\d{1,2})?$", "example": "300.00" }, "date": { "description": "Y-m-d, on or after the advance's payout and no later than the company's today.", "type": "string", "format": "date", "example": "2026-10-02" } }, "type": "object" } } } }, "responses": { "201": { "description": "Applied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupplierCreditApplication" } } } }, "200": { "description": "The same id was already applied with the same terms; nothing was written", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupplierCreditApplication" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentMiddlewareError" } } } }, "403": { "description": "The user lacks backoffice.purchases.payments.apply-credit" }, "409": { "description": "credit_balance_exceeded: the units exceed what the advance holds now; supplier_credit_application_id_conflict: the id is used with other terms or by another company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupplierCreditApplicationProblem" } } } }, "422": { "description": "Validation (errors); payment_not_found or purchases_invoice_not_found for a body reference; application_source_not_open (not a paid-out advance); application_target_not_open (a draft, cancelled or fully paid document); application_counterparty_mismatch (another provider's document); application_date_precedes_advance; application_exceeds_open_balance; application_settles_nothing; cash_event_date_in_the_future; unsupported_cash_event_currency. A missing accounting configuration answers the readiness envelope instead: OFFICIAL_RATE_STALE, OFFICIAL_RATE_NOT_AVAILABLE, PAYABLE_ACCOUNT_MISSING, PAYABLE_ACCOUNT_INACTIVE, PAYABLE_CENTER_MISSING, EXCHANGE_POSTING_ACCOUNT_MISSING, ACCOUNTING_PERIOD_CLOSED or LEDGER_FLOW_NOT_PARALLEL_CURRENCY_READY.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/SupplierCreditApplicationProblem" }, { "$ref": "#/components/schemas/PaymentAccountingConfigurationError" } ] } } } }, "500": { "description": "A broken stored invariant or a failed write; the transaction rolls back.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupplierCreditApplicationProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/credit-applications/preview": { "get": { "tags": [ "Backoffice - Purchases Credit Applications" ], "summary": "Preview applying a supplier advance to a payable document", "description": "What applying the advance's units to the document on the date would record (MER-3276), by the same eligibility, Rate Snapshot rule, settlement and accounting readiness as applying, with nothing locked or written: it refuses exactly what applying would. Without source_units it proposes the lesser of what the advance holds and the units that settle the document in full at that snapshot. Requires backoffice.purchases.payments.apply-credit.", "operationId": "previewSupplierCreditApplication", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "source_type", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "payment", "credit_note" ] } }, { "name": "source_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "target_type", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "purchases_invoice" ] } }, { "name": "target_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "source_units", "in": "query", "description": "Greater than zero, at most two decimals, in the advance's currency; omitted, the preview proposes them.", "required": false, "schema": { "type": "string", "pattern": "^(?!0+(?:\\.0{1,2})?$)\\d{1,13}(?:\\.\\d{1,2})?$" } }, { "name": "date", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "What applying would record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupplierCreditApplicationPreview" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentMiddlewareError" } } } }, "403": { "description": "The user lacks backoffice.purchases.payments.apply-credit" }, "409": { "description": "credit_balance_exceeded: the units exceed what the advance holds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupplierCreditApplicationProblem" } } } }, "422": { "description": "The refusals of applying: validation (errors), payment_not_found, purchases_invoice_not_found, application_source_not_open, application_target_not_open, application_counterparty_mismatch, application_date_precedes_advance, application_exceeds_open_balance, application_settles_nothing, cash_event_date_in_the_future, unsupported_cash_event_currency, or the readiness envelope.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/SupplierCreditApplicationProblem" }, { "$ref": "#/components/schemas/PaymentAccountingConfigurationError" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/credit-applications/{id}/revert": { "post": { "tags": [ "Backoffice - Purchases Credit Applications" ], "summary": "Unapply a supplier credit application from a payable document", "description": "Unapplies a rate-bearing Supplier Credit Application (MER-3276, MER-4716): the document and the source (a supplier advance or a credit note's Supplier Credit) get back exactly what it relieved, never valued again, and its entry is inverted line by line in both books by purchase_credit.reverted, dated at the company's today and linked by reverses_transaction_id. Repeating it answers 200 with the application as it stands, without writes. An application recorded at credit-note approval (no Rate Snapshot) reverts only with its note (422 application_not_revertible). Requires backoffice.purchases.payments.apply-credit.", "operationId": "revertSupplierCreditApplication", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Unapplied, now or before", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupplierCreditApplication" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentMiddlewareError" } } } }, "403": { "description": "The user lacks backoffice.purchases.payments.apply-credit" }, "404": { "description": "supplier_credit_application_not_found: no application of the company has that id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupplierCreditApplicationProblem" } } } }, "422": { "description": "application_not_revertible: it applies a supplier credit note", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupplierCreditApplicationProblem" } } } }, "500": { "description": "A broken stored invariant (supplier_credit_application_integrity_error, purchase_credit_application_posted_transaction_missing) or a failed write; the transaction rolls back.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupplierCreditApplicationProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/credit-notes/{id}/applications": { "get": { "tags": [ "Backoffice - Purchases Credit Notes" ], "summary": "Read only this supplier credit note applications", "operationId": "listPurchasesCreditNoteApplications", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "This note applications, active and reverted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupplierCreditApplicationList" } } } }, "403": { "description": "Requires supplier credit note view permission" }, "404": { "description": "Missing, foreign-company or non-credit-note id" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/credit-notes/{id}/approve": { "post": { "tags": [ "Backoffice - Purchases Credit Notes" ], "summary": "Approve a draft supplier credit note", "description": "Approves a draft Supplier Credit Note in one transaction, locking its origin purchases invoice before the note. Its lines are valued again at the caps its origin's approved notes leave, each line's cap raised by what the origin's approved supplier debit notes added to it (MER-3291), and each tax group as the exact share of the origin's frozen valuation raised by those debit notes' linked share; the note that leaves a group with nothing to credit takes its exact remainder. The supplier's captured bolívars win the functional book when it is the statutory one, within a cent per note line of the share and never beyond what the group still holds; the reporting book keeps the share. The note relieves the origin's open balance up to what the origin owes, through a Supplier Credit Application, and the origin's status follows its balance without any payment; what is left stays as the note's Supplier Credit (status with_supplier_credit, or applied when nothing is left). The approval posts the purchase_credit_note.approved entry dated at the note's registration date: the payable is debited, and the purchase returns and the tax are credited, the tax on the account its origin's approval debited. When the company cannot post it, the approval answers 422 accounting_configuration_incomplete naming each missing configuration, such as PURCHASE_RETURNS_ACCOUNT_MISSING with details [purchase_returns], and writes nothing. It takes no body; repeating an approval answers 200 with the same body and writes nothing. Requires `backoffice.purchases.credit-notes.approve`.", "operationId": "approvePurchasesCreditNote", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Credit note approved, or already approved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchasesCreditNoteApproved" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks backoffice.purchases.credit-notes.approve" }, "404": { "description": "purchase_credit_note_not_found, also for an invoice id", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "detail": { "type": "string" }, "error_code": { "type": "string", "enum": [ "purchase_credit_note_not_found" ] } }, "type": "object" } } } }, "422": { "description": "The note is cancelled (purchase_credit_note_cannot_be_approved); its origin can no longer be credited (the PurchasesNoteInvalidOrigin body, whose cause may now be without_valuation); a line is above what its origin line still has (the PurchasesCreditNoteLineCapExceeded body), a unit return is worth nothing left (purchase_credit_note_line_without_amount), or a line's tax group was already credited in full by the approved notes, so the note would credit nothing (purchase_credit_note_group_without_value); a group credit is above what remains of it (tax_group_credit_exceeds_remainder); one capture names two of the note's tax groups (purchases_invoice_captured_amounts_group_mismatch); the control line values to 0.00 in both books (document_values_to_zero_in_both_books); or the entry cannot post, answered as {error: accounting_configuration_incomplete, missing: [{reason_code, subject_type, subject_id, human_message, details}]}.", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string" }, "error_code": { "type": "string", "example": "purchase_credit_note_cannot_be_approved", "nullable": true }, "cause": { "description": "Only on purchase_note_invalid_origin.", "type": "string", "enum": [ "not_found", "opening", "not_approved", "cancelled", "is_a_note", "without_valuation" ] }, "error": { "description": "Only on a globally rendered refusal: line_credit_cap_exceeded or accounting_configuration_incomplete.", "type": "string" }, "missing": { "description": "Only on accounting_configuration_incomplete.", "type": "array", "items": { "type": "object" } } }, "type": "object" } } } }, "500": { "description": "The entry could not be persisted, or a broken invariant" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/credit-notes/{id}/cancel": { "post": { "tags": [ "Backoffice - Purchases Credit Notes" ], "summary": "Cancel a supplier credit note", "description": "Cancels a Supplier Credit Note in one transaction, locking its origin purchases invoice, then the note, then its active Supplier Credit Applications. A draft is cancelled without an entry, and its supplier number becomes free. An approved note restores its origin exactly from each application's stored amounts (the origin's status follows its balance, with no payment), marks each one reverted, gets back what it gave up, and posts `purchase_credit_note.cancelled`: the line-by-line inversion of its `purchase_credit_note.approved` entry in both books, rounding included, dated the company's today and naming that entry in `reverses_transaction_id`. A note whose credit relieved another invoice answers 409 `purchase_credit_note_credit_used_elsewhere` and writes nothing. Cancelling again answers 200 with `restored_amount` 0.00 and writes nothing. It takes no body. A note the current Declared Set of a Fiscal Period in review or closed holds answers 409 `document_in_frozen_fiscal_period` before anything is locked, naming the period in `fiscal_period` (MER-3837). Requires `backoffice.purchases.credit-notes.cancel`.", "operationId": "cancelPurchasesCreditNote", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Credit note cancelled, or already cancelled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchasesCreditNoteCancelled" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks backoffice.purchases.credit-notes.cancel" }, "404": { "description": "purchase_credit_note_not_found, also for an invoice id", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "detail": { "type": "string" }, "error_code": { "type": "string", "enum": [ "purchase_credit_note_not_found" ] }, "errors": { "type": "object", "nullable": true } }, "type": "object" } } } }, "409": { "description": "The note's credit relieved an invoice other than its origin (purchase_credit_note_credit_used_elsewhere), or a frozen fiscal period declared it (document_in_frozen_fiscal_period, with `fiscal_period`); nothing is written.", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "detail": { "type": "string" }, "error_code": { "type": "string", "enum": [ "purchase_credit_note_credit_used_elsewhere", "document_in_frozen_fiscal_period" ] }, "errors": { "type": "object", "nullable": true }, "fiscal_period": { "description": "Only on document_in_frozen_fiscal_period: the period whose current Declared Set holds the document.", "allOf": [ { "$ref": "#/components/schemas/FrozenFiscalPeriod" } ] } }, "type": "object" } } } }, "500": { "description": "The approved entry is missing (purchase_credit_note_posted_transaction_missing) or already reversed, the cancellation could not be persisted, or a broken invariant" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/credit-notes/{id}": { "get": { "tags": [ "Backoffice - Purchases Credit Notes" ], "summary": "Show a supplier credit note", "description": "A Supplier Credit Note of this company with its origin invoice, reason, own fiscal identity, lines, captured Bs and valuation. While the note is a draft its balance and parallel balances are 0.00 and its parallel totals are an estimate at the origin's frozen rate; tax_summaries are filled only when captures exist. An invoice id answers 404. Requires `backoffice.purchases.credit-notes.view`.", "operationId": "getPurchasesCreditNote", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The credit note", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchasesCreditNoteDetail" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks backoffice.purchases.credit-notes.view" }, "404": { "description": "purchase_credit_note_not_found" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/credit-notes/source-invoice/{id}": { "get": { "tags": [ "Backoffice - Purchases - Supplier Notes" ], "summary": "Approved invoice facts for this supplier note, without invoice management access", "operationId": "e3c77403c006a20d50f095794f3cb78e", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Only the supplier note origin projection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchasesNoteOriginSource" } } } }, "403": { "description": "This supplier note create permission required" }, "404": { "description": "Origin not found in this company" }, "422": { "description": "Origin must be an approved regular invoice", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchasesNoteInvalidOrigin" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/credit-notes": { "post": { "tags": [ "Backoffice - Purchases Credit Notes" ], "summary": "Register a supplier credit note from its origin purchases invoice", "description": "Registers a Supplier Credit Note as a draft (status to_be_approved) against an approved regular purchases invoice of this company, paid ones included. The note inherits the origin's provider, currency, frozen rate snapshot, provider fiscal snapshot, payable account, accounting center, payment term and location, never its purchase order, contract or reference; it owes nothing (balance 0.00) and posts nothing until it is approved. Its code is NCP, the two-digit year and its own five-digit correlative, and it is registered on the company's today. Each line credits one origin line, at most once per note: a unit_return is valued at the line's net unit price, an amount_rebate states its amount, and both must stay within what the line invoiced plus what the origin's approved supplier debit notes added to it (MER-3291), less what its approved credit notes took (422 line_credit_cap_exceeded with the units and amount still available); drafts and cancelled notes never count. A unit_return whose units have no amount left to credit is refused (purchase_credit_note_line_without_amount). The origin must exist and be an approved regular invoice: otherwise 422 purchase_note_invalid_origin with a cause of not_found, opening, not_approved, cancelled or is_a_note. The emission date falls between the origin's emission date (purchase_credit_note_emission_date_precedes_origin) and the company's today (purchases_invoice_registration_date_out_of_range). The provider numbers are kept as printed like an invoice's (ADR 0380); the provider invoice number is unique among the provider's live credit notes, compared without whitespace or case (º counts as O), so one another live credit note holds answers 409 naming its code and kind, while an invoice holding the same number does not clash. captured_amounts, in the statutory books currency, must follow the note's own tax groups; until approval they value the note as a preview at the origin's rate. While the company's Fiscal Profile guards are on, a new note must already carry what its approval will require, checked before its code is drawn: provider_invoice_number when the origin froze a provider fiscal snapshot, control_number too when that provider holds a RIF or cédula, and captured_amounts when that Fiscal Profile names a statutory books currency and the note's currency differs from it; otherwise 422 purchases_note_registration_incomplete names the missing fields in `errors`. A replay is not asked them again. The client generates the UUID `id`: resending it with the same terms answers 200 with the same body; with other terms, or an id another document holds, 409 purchase_credit_note_id_conflict. The client also generates each line `id`: one that a line of any other document already holds answers 409 purchase_credit_note_line_id_conflict. Requires `backoffice.purchases.credit-notes.create`.", "operationId": "registerPurchasesCreditNote", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "id", "origin_purchases_invoice_id", "emission_date", "reason", "lines" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "0199a000-0000-7000-8000-0000000003a1" }, "origin_purchases_invoice_id": { "description": "The approved regular purchases invoice this note affects.", "type": "string", "format": "uuid", "example": "0199a000-0000-7000-8000-0000000000a1" }, "emission_date": { "description": "On or after the origin's emission date and no later than the company's today.", "type": "string", "format": "date", "example": "2026-09-28" }, "reason": { "type": "string", "example": "discount", "enum": [ "return", "discount", "price_correction", "quantity_correction", "other" ] }, "observations": { "description": "A free explanation of the reason.", "type": "string", "nullable": true }, "provider_invoice_number": { "description": "The note's own printed number, kept as printed (ADR 0380): trimmed, with case, inner spaces and leading zeros kept, 1 to 30 letters, digits, spaces, hyphens, ° or º. Blank means absent.", "type": "string", "example": "NC-45", "nullable": true, "maxLength": 60 }, "control_number": { "description": "The note's own fiscal control number, kept as printed like provider_invoice_number.", "type": "string", "example": "00-12345", "nullable": true, "maxLength": 60 }, "captured_amounts": { "description": "The statutory base and tax per tax group of the note, one per tax and rate.", "type": "array", "items": { "$ref": "#/components/schemas/PurchasesCapturedAmountInput" }, "nullable": true }, "lines": { "description": "Line ids and origin lines are each distinct.", "type": "array", "items": { "$ref": "#/components/schemas/PurchasesCreditNoteLineInput" }, "minItems": 1 } }, "type": "object" } } } }, "responses": { "201": { "description": "Credit note registered as a draft", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchasesCreditNoteRegistered" } } } }, "200": { "description": "The same id was already registered with the same terms; nothing was written", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchasesCreditNoteRegistered" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks backoffice.purchases.credit-notes.create" }, "409": { "description": "purchase_credit_note_id_conflict: the id is already used with other terms or by another document; purchase_credit_note_line_id_conflict: a line id is already used by a line of another document; or purchases_invoice_provider_number_already_registered, which also carries existing_code and existing_kind (see PurchasesDocumentProviderNumberConflict)", "content": { "application/json": { "schema": { "required": [ "title", "status", "detail", "error_code" ], "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "detail": { "type": "string" }, "error_code": { "type": "string", "enum": [ "purchase_credit_note_id_conflict", "purchase_credit_note_line_id_conflict", "purchases_invoice_provider_number_already_registered" ] }, "existing_code": { "description": "Only on purchases_invoice_provider_number_already_registered: the code of the document that holds the number, empty when it cannot be named.", "type": "string", "example": "NCP2600001" }, "existing_kind": { "description": "Only on purchases_invoice_provider_number_already_registered: the kind of that document, null exactly when existing_code is empty.", "type": "string", "nullable": true, "enum": [ "regular", "opening", "credit_note", "debit_note" ] } }, "type": "object" } } } }, "422": { "description": "Validation error (`errors`); a refused origin (purchase_note_invalid_origin with its `cause`, see PurchasesNoteInvalidOrigin); a date before the origin (purchase_credit_note_emission_date_precedes_origin); refused lines (purchase_credit_note_without_lines, purchase_credit_note_line_repeated, purchase_credit_note_origin_line_repeated, purchase_credit_note_origin_line_not_found, purchase_credit_note_line_credit_not_positive, purchase_credit_note_line_without_amount, purchase_credit_note_line_type_unknown); invalid_purchase_credit_note_reason; invalid_provider_invoice_number or invalid_control_number; purchases_note_registration_incomplete under the Fiscal Profile guards, whose `errors` holds only the missing ones of provider_invoice_number, control_number and captured_amounts; purchases_invoice_captured_amounts_group_mismatch or an invalid capture; purchases_invoice_total_exceeds_storage; line_credit_cap_returned_units_exceed_creditable or line_credit_cap_credited_amount_exceeds_creditable when the origin line's approved credit notes already exceed what it invoiced (drifted data). A line above its cap answers the PurchasesCreditNoteLineCapExceeded body instead, and an emission date after the company's today `{error: purchases_invoice_registration_date_out_of_range, detail, field}`.", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string" }, "error_code": { "type": "string", "example": "purchase_note_invalid_origin", "nullable": true }, "cause": { "description": "Only on purchase_note_invalid_origin.", "type": "string", "enum": [ "not_found", "opening", "not_approved", "cancelled", "is_a_note" ] }, "errors": { "description": "The offending request fields, each with its messages.", "type": "object", "nullable": true }, "error": { "description": "Only on a globally rendered refusal: line_credit_cap_exceeded or purchases_invoice_registration_date_out_of_range.", "type": "string" }, "field": { "description": "Only on purchases_invoice_registration_date_out_of_range.", "type": "string" }, "line_id": { "description": "Only on line_credit_cap_exceeded.", "type": "string", "format": "uuid" }, "available_units": { "description": "Only on line_credit_cap_exceeded.", "type": "string" }, "available_amount": { "description": "Only on line_credit_cap_exceeded.", "type": "string" }, "currency": { "description": "Only on line_credit_cap_exceeded.", "type": "string" } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/purchases-invoices/{id}/creditable-lines": { "get": { "tags": [ "Backoffice - Purchases Credit Notes" ], "summary": "What each line of a purchases invoice can still credit", "description": "For an approved regular purchases invoice, each line with what it invoiced (its units, and its amount net of the line discount), what the invoice's approved supplier debit notes added to it through linked increases (increased_*, MER-3291), what its approved credit notes already returned and credited, and what is still available (invoiced plus increased, less credited), with the origin's frozen rate snapshot to estimate captured Bs from. Draft and cancelled notes do not count, so the availability is a preview that approval checks again. An invoice that cannot be credited answers 422 purchase_note_invalid_origin with the same cause registration would give. Requires `backoffice.purchases.credit-notes.create`.", "operationId": "getPurchasesInvoiceCreditableLines", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The creditable lines", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchasesInvoiceCreditableLines" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks backoffice.purchases.credit-notes.create" }, "404": { "description": "purchases_invoice_not_found: an unknown id or a note's id" }, "422": { "description": "purchase_note_invalid_origin with cause opening, not_approved or cancelled; or line_credit_cap_returned_units_exceed_creditable / line_credit_cap_credited_amount_exceeds_creditable when the approved credit notes already exceed what a line invoiced (drifted data)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchasesNoteInvalidOrigin" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/debit-notes/{id}/accounting-readiness": { "get": { "tags": [ "Backoffice - Purchases Debit Notes" ], "summary": "Get accounting readiness for a draft supplier debit note", "description": "What keeps a draft Supplier Debit Note from approval at the standard VAT withholding rule (MER-5386), in the order its approval checks: the origin's payable account and settlement center, each line's expense account and center, the tax accounts (a company that is not an ordinary VAT taxpayer on the note's own registration date misses NON_DEDUCTIBLE_VAT_ACCOUNT_MISSING, subject company, details [non_deductible_vat], and never VAT_INPUT_ACCOUNT_MISSING, MER-5393), its VAT withholding reasons (COMPANY_TAX_ATTRIBUTES_NOT_CONFIGURED, RULE_NOT_IN_FORCE, WITHHOLDING_REASON_REQUIRED, VAT_WITHHOLDING_EXCLUSION_REQUIRED on the provider with details [art3_n2_supplier_formal_taxpayer] when the supplier the note inherited from its origin is a formal VAT taxpayer, FISCAL_ACCOUNT_MISSING with details [vat_withholding_payable]), its ISLR withholding reasons (ISLR_ITEM_CLASSIFICATION_MISSING on an inventory_item with details [lines.{n}, {line id}] for a line neither its origin line nor its item classifies, ISLR_PERSON_TYPE_MISSING on the provider, ISLR_CONCEPT_NOT_ENABLED on an invoice_item with details [lines.{n}, {concept}:{person_type}, {disposition}], RULE_NOT_IN_FORCE, FISCAL_ACCOUNT_MISSING with details [islr_withholding_payable]), the parallel-currency flow, the supplier's fiscal document and captures under the fiscal-profile guards, and the closed period of its registration date last; and what the proposed rule would withhold from its VAT at its origin's frozen rate (`vat_withholding_proposal`, null when nothing would be withheld or it cannot be told). A note carries no warnings. Requires `backoffice.purchases.debit-notes.view`.", "operationId": "getPurchasesDebitNoteAccountingReadiness", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Accounting readiness snapshot of the draft", "content": { "application/json": { "schema": { "required": [ "ready", "missing", "warnings", "vat_withholding_proposal" ], "properties": { "ready": { "type": "boolean" }, "missing": { "type": "array", "items": { "properties": { "reason_code": { "type": "string" }, "subject_type": { "type": "string" }, "subject_id": { "type": "string" }, "human_message": { "type": "string" }, "details": { "type": "array", "items": { "type": "string" } } }, "type": "object" } }, "warnings": { "$ref": "#/components/schemas/AccountingReadinessWarnings" }, "vat_withholding_proposal": { "$ref": "#/components/schemas/VatWithholdingProposal" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks backoffice.purchases.debit-notes.view" }, "404": { "description": "purchase_debit_note_not_found, also for an invoice or credit note id", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "detail": { "type": "string" }, "error_code": { "type": "string", "enum": [ "purchase_debit_note_not_found" ] } }, "type": "object" } } } }, "409": { "description": "The note is no longer a draft, so it has nothing to approve (purchase_debit_note_cannot_be_approved).", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "detail": { "type": "string" }, "error_code": { "type": "string", "enum": [ "purchase_debit_note_cannot_be_approved" ] } }, "type": "object" } } } }, "422": { "description": "Its origin can no longer be debited, answered with the PurchasesNoteInvalidOrigin body (error_code purchase_note_invalid_origin and its cause).", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string" }, "error_code": { "type": "string", "example": "purchase_note_invalid_origin" }, "cause": { "type": "string", "enum": [ "not_found", "opening", "not_approved", "cancelled", "is_a_note" ] } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/debit-notes/{id}/approve": { "post": { "tags": [ "Backoffice - Purchases Debit Notes" ], "summary": "Approve a draft supplier debit note", "description": "Approves a draft Supplier Debit Note in one transaction, locking its origin purchases invoice before the note. The note is valued at its origin's frozen rate snapshot, never at the rate of its own dates: each tax group's base is converted and taxed on the converted base, and the supplier's captured bolívars win the functional book when it is the statutory one, within a cent per line of the group. It becomes to_be_paid and owes its total in its three books. The approval posts the purchase_debit_note.approved entry dated at the note's registration date: each line's expense account and center are debited, the VAT Input Account is debited with the tax (or the tax's own account), or, for a company that is not an ordinary VAT taxpayer on the note's registration date, its non-deductible VAT account (MER-5393), and the origin's payable is credited on the center the origin's payable settles on. Under a Company Fiscal Profile, a company designated VAT withholding agent on the note's registration date withholds, in the same transaction, the rule's share of the note's own VAT in bolívars (MER-5386): the standard 75 % unless `vat_withholding_reason` names an art. 5 cause (100 %) or an art. 3 exclusion (0 %), each with its supporting note; an exclusion also requires `backoffice.fiscal.withholdings.review`. The supplier is the one the note inherited from its origin: when it is a formal VAT taxpayer only an art. 3 exclusion is accepted (`art3_n2_supplier_formal_taxpayer`), and the standard rule or an art. 5 cause answers 422 accounting_configuration_incomplete with VAT_WITHHOLDING_EXCLUSION_REQUIRED. A company designated ISLR withholding agent also withholds ISLR on the note's lines: a linked increase pays the ISLR concept of its origin line, a new concept (or a linked line whose origin line has none) its item's default; a line neither classifies answers ISLR_ITEM_CLASSIFICATION_MISSING on the item (details [lines.{n}, {line id}]). Each withholding relieves the note's payable, so it owes its total less `withheld_amount`, gets its numbered withholding certificate when it withholds something, and posts its vat_withholding.determined or islr_withholding.determined entry. When the company cannot post or withhold, the approval answers 422 accounting_configuration_incomplete naming each missing configuration, the withholding reasons after the tax ones and ACCOUNTING_PERIOD_CLOSED last on the registration date, and writes nothing. The body is optional; repeating an approval answers 200 with the note's current status, which may already be partially_paid or fully_paid, and writes nothing. Requires `backoffice.purchases.debit-notes.approve`.", "operationId": "approvePurchasesDebitNote", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "vat_withholding_reason": { "description": "Optional Withholding Reason for the VAT withholding the approval determines (MER-5386). Omitted, null or code `standard` applies the standard rule.", "required": [ "code" ], "properties": { "code": { "description": "A rule code of the VAT withholding rates catalog in force on the note's registration date.", "type": "string", "pattern": "^[a-z0-9_]{1,64}$", "example": "art3_n2_supplier_formal_taxpayer" }, "note": { "description": "The note that supports an art. 3 or art. 5 cause; required by them.", "type": "string", "example": "Proveedor contribuyente formal de IVA", "nullable": true, "maxLength": 500 } }, "type": "object", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Debit note approved, or already approved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchasesDebitNoteApproved" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks backoffice.purchases.debit-notes.approve, or chose an art. 3 exclusion without backoffice.fiscal.withholdings.review (error_code vat_withholding_exclusion_requires_review). Nothing is written." }, "404": { "description": "purchase_debit_note_not_found, also for an invoice or credit note id", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "detail": { "type": "string" }, "error_code": { "type": "string", "enum": [ "purchase_debit_note_not_found" ] } }, "type": "object" } } } }, "409": { "description": "A withholding of the note was already determined (vat_withholding_already_determined, islr_withholding_already_determined), or the company's certificate series is exhausted (certificate_sequence_exhausted), or an Item the note revalues moved its stock while the approval waited for its locks (inventory_cost_revaluation_raced; send it again). Nothing is written.", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "detail": { "type": "string" }, "error_code": { "type": "string", "enum": [ "vat_withholding_already_determined", "islr_withholding_already_determined", "certificate_sequence_exhausted", "inventory_cost_revaluation_raced" ] } }, "type": "object" } } } }, "422": { "description": "A certificate issued from the legal effective day requires the provider email; otherwise error_code withholding_provider_email_required with provider_id, provider_name and purchases_invoice_id (this debit note), and the whole approval rolls back. Request validation failed (`message` and `errors` keyed by field); the note is cancelled (purchase_debit_note_cannot_be_approved); its origin can no longer be debited (the PurchasesNoteInvalidOrigin body); one capture names two of the note's tax groups (purchases_invoice_captured_amounts_group_mismatch); the entry cannot post or a withholding cannot be determined, answered as {error: accounting_configuration_incomplete, missing: [{reason_code, subject_type, subject_id, human_message, details}]} with its withholding reasons (COMPANY_TAX_ATTRIBUTES_NOT_CONFIGURED, RULE_NOT_IN_FORCE, WITHHOLDING_REASON_REQUIRED, VAT_WITHHOLDING_EXCLUSION_REQUIRED on the provider with details [art3_n2_supplier_formal_taxpayer], FISCAL_ACCOUNT_MISSING with details [vat_withholding_payable] or [islr_withholding_payable], ISLR_ITEM_CLASSIFICATION_MISSING on an inventory_item with details [lines.{n}, {line id}], ISLR_PERSON_TYPE_MISSING on the provider, ISLR_CONCEPT_NOT_ENABLED on an invoice_item with details [lines.{n}, {concept}:{person_type}, {disposition}]); or a withholding refusal raced past the readiness (error_code company_tax_attributes_not_configured, rule_not_in_force, withholding_reason_required, vat_withholding_exclusion_required, invalid_vat_withholding_rate, islr_classification_missing, islr_person_type_missing or islr_concept_not_enabled).", "content": { "application/json": { "schema": { "oneOf": [ { "properties": { "message": { "description": "Only on a validation failure.", "type": "string" }, "errors": { "description": "Only on a validation failure: the messages by field.", "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string" }, "error_code": { "description": "Any other refusal; withholding_provider_email_required has its own schema.", "type": "string", "example": "purchase_debit_note_cannot_be_approved", "nullable": true }, "cause": { "description": "Only on purchase_note_invalid_origin.", "type": "string", "enum": [ "not_found", "opening", "not_approved", "cancelled", "is_a_note" ] }, "error": { "description": "Only on a globally rendered refusal: accounting_configuration_incomplete.", "type": "string" }, "missing": { "description": "Only on accounting_configuration_incomplete.", "type": "array", "items": { "type": "object" } } }, "type": "object" }, { "description": "A withholding certificate issued from the PA SNAT/2026/00093 effective day requires the provider email (MER-5641, ADR 0352). Nothing is written.", "required": [ "title", "status", "detail", "error_code", "errors", "provider_id", "provider_name", "purchases_invoice_id" ], "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422, "enum": [ 422 ] }, "detail": { "type": "string", "example": "Completa el correo del proveedor Servicios Ejemplo, C.A. en su ficha antes de aprobar: el comprobante de retención lo requiere." }, "error_code": { "type": "string", "example": "withholding_provider_email_required", "enum": [ "withholding_provider_email_required" ] }, "errors": { "type": "object", "example": null, "nullable": true }, "provider_id": { "description": "The provider whose email is missing.", "type": "string", "format": "uuid" }, "provider_name": { "description": "The provider's legal name, or its id when it has none.", "type": "string", "example": "Servicios Ejemplo, C.A." }, "purchases_invoice_id": { "description": "The debit note itself, the document whose certificate needs the email.", "type": "string", "format": "uuid" } }, "type": "object" } ] } } } }, "500": { "description": "The entry could not be persisted, or a broken invariant" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/debit-notes/{id}/cancel": { "post": { "tags": [ "Backoffice - Purchases Debit Notes" ], "summary": "Cancel a supplier debit note", "description": "Cancels a Supplier Debit Note in one transaction, locking its origin purchases invoice before the note. A draft is cancelled without an entry, and its supplier number becomes free. An unpaid approved note keeps its balances as they stood and posts `purchase_debit_note.cancelled`: the line-by-line inversion of its `purchase_debit_note.approved` entry in both books, dated the company's today and naming that entry in `reverses_transaction_id`; `reversed_amount` is its total. A partially or fully paid note answers 409 `purchase_debit_note_has_payments`: cancel its payments first. A note whose linked increase an approved supplier credit note credits answers 409 `purchase_debit_note_increase_credited`, naming the origin lines and the origin's approved credit notes: cancel those first. A note whose VAT or ISLR withholding was remitted to SENIAT answers 409 `remitted_withholding_requires_adjustment`, naming the note and each remitted tax: correct it with a credit note on its origin and an adjustment of the withholding (MER-5386). Each refusal writes nothing. Otherwise cancelling an unpaid approved note also voids the withholdings its approval determined, with reason «Nota de débito cancelada»: what each withheld is owed again on the cancelled note, each certificate is voided keeping its number and each withholding entry is reversed. A note whose increase on received purchase-order units revalued the cost of an Item (MER-5385) also reverts that Inventory Cost Revaluation: the Item gives back the share it put on hand and `inventory_cost.revaluation_reverted` inverts the `inventory_cost.revalued` entry; while an Item no longer holds stock carrying that share, it answers 422 `inventory_cost_revaluation_cannot_be_reverted` and writes nothing. A note approved before some of its purchase-order units arrived left their share of its increase on In-Transit, and the receipt that brought them priced them at it (MER-5520): once one did, its price is in the Item's cost and cancelling would credit In-Transit by it again, so the note answers 422 `inventory_cost_taken_by_receipt` and writes nothing. Cancelling again answers 200 with `reversed_amount` 0.00 and writes nothing. It takes no body. A note the current Declared Set of a Fiscal Period in review or closed holds answers 409 `document_in_frozen_fiscal_period` before anything is locked, naming the period in `fiscal_period` (MER-3837). Requires `backoffice.purchases.debit-notes.cancel`.", "operationId": "cancelPurchasesDebitNote", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Debit note cancelled, or already cancelled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchasesDebitNoteCancelled" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks backoffice.purchases.debit-notes.cancel" }, "404": { "description": "purchase_debit_note_not_found, also for an invoice or credit note id", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "detail": { "type": "string" }, "error_code": { "type": "string", "enum": [ "purchase_debit_note_not_found" ] }, "errors": { "type": "object", "nullable": true } }, "type": "object" } } } }, "409": { "description": "The note has payments (purchase_debit_note_has_payments), an approved credit note credits what it added (purchase_debit_note_increase_credited, with origin_purchases_invoice_item_ids and credit_notes), a withholding of it was remitted to SENIAT (remitted_withholding_requires_adjustment, MER-5386), or a frozen fiscal period declared it (document_in_frozen_fiscal_period, with `fiscal_period`), or an Item its revaluation gave cost to moved its stock while the cancellation waited for its locks (inventory_cost_revaluation_raced; send it again); nothing is written.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchasesDebitNoteCancellationConflict" } } } }, "422": { "description": "An Item whose cost the note revalued no longer holds stock carrying the share it put on hand (inventory_cost_revaluation_cannot_be_reverted, MER-5385), or a receipt priced units the note raised at its price after its approval (inventory_cost_taken_by_receipt, MER-5520); nothing is written.", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string" }, "error_code": { "type": "string", "enum": [ "inventory_cost_revaluation_cannot_be_reverted", "inventory_cost_taken_by_receipt" ] }, "errors": { "type": "object", "nullable": true } }, "type": "object" } } } }, "500": { "description": "The approved entry is missing (purchase_debit_note_posted_transaction_missing) or already reversed, the cancellation could not be persisted, or a broken invariant" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/debit-notes/{id}": { "get": { "tags": [ "Backoffice - Purchases Debit Notes" ], "summary": "Show a supplier debit note", "description": "A Supplier Debit Note of this company with its origin invoice, reason, own fiscal identity, lines, captured Bs and valuation. Its balance is the open debt: 0.00 while it is a draft, its total once approved, what remains after payments, and as it stood once cancelled. While the note is a draft its parallel totals are an estimate at the origin's frozen rate. An invoice or credit note id answers 404. Requires `backoffice.purchases.debit-notes.view`.", "operationId": "getPurchasesDebitNote", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The debit note", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchasesDebitNoteDetail" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks backoffice.purchases.debit-notes.view" }, "404": { "description": "purchase_debit_note_not_found" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/debit-notes/item-defaults/{id}": { "get": { "tags": [ "Backoffice - Purchases - Supplier Notes" ], "summary": "Only the defaults needed to prepare a new supplier debit note concept", "operationId": "getPurchasesDebitNoteItemDefaults", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Name, category, canonical purchase account and configured purchase unit", "content": { "application/json": { "schema": { "required": [ "name", "category_id", "accounting_account_id" ], "properties": { "default_unit_id": { "description": "The configured purchase or sale unit for this document kind; null keeps the existing base/only-unit fallback.", "type": "string", "format": "uuid", "nullable": true }, "name": { "type": "string" }, "category_id": { "type": "string", "format": "uuid" }, "accounting_account_id": { "type": "string", "format": "uuid", "nullable": true } }, "type": "object" } } } }, "403": { "description": "Requires supplier debit note create permission" }, "404": { "description": "Item not found in this company" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/debit-notes/source-invoice/{id}": { "get": { "tags": [ "Backoffice - Purchases - Supplier Notes" ], "summary": "Approved invoice facts for this supplier note, without invoice management access", "operationId": "b7c406d98bf41ded938d31dd4256f064", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Only the supplier note origin projection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchasesNoteOriginSource" } } } }, "403": { "description": "This supplier note create permission required" }, "404": { "description": "Origin not found in this company" }, "422": { "description": "Origin must be an approved regular invoice", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchasesNoteInvalidOrigin" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/debit-notes": { "post": { "tags": [ "Backoffice - Purchases Debit Notes" ], "summary": "Register a supplier debit note against its origin purchases invoice", "description": "Registers a Supplier Debit Note as a draft (status to_be_approved) against an approved regular purchases invoice of this company, paid ones included. The note inherits the origin's provider, currency, frozen rate snapshot, provider fiscal snapshot, payable account, accounting center, payment term and location; it owes nothing (balance 0.00) and posts nothing until it is approved. Its code is NDP, the two-digit year and its own five-digit correlative, and it is registered on the company's today. A linked_increase raises one origin line, at most once per note, by `units` valued at the line's own net unit price or by the `amount` it states; a new_concept brings its own category, item, unit, quantity, unit price, expense account and center, priced like an invoice line with no discount, and is taxed only by one of the origin's tax groups (tax_id and tax_percentage), otherwise 422 purchase_debit_note_new_concept_tax_not_in_origin. Its item, category, unit, account and center must be active records of this company (422 purchases_invoice_references_not_bindable). The origin must exist and be an approved regular invoice: otherwise 422 purchase_note_invalid_origin with a cause of not_found, opening, not_approved, cancelled or is_a_note. The emission date falls between the origin's emission date (purchase_debit_note_emission_date_precedes_origin) and the company's today (purchases_invoice_registration_date_out_of_range). The provider invoice number is unique among the provider's live debit notes, so one another live debit note holds answers 409 naming its code and kind, while an invoice or a credit note holding the same number does not clash. captured_amounts, in the statutory books currency, must follow the note's own tax groups. While the company's Fiscal Profile guards are on, a new note must already carry what its approval will require, checked before its code is drawn: provider_invoice_number when the origin froze a provider fiscal snapshot, control_number too when that provider holds a RIF or cédula, and captured_amounts when that Fiscal Profile names a statutory books currency and the note's currency differs from it; otherwise 422 purchases_note_registration_incomplete names the missing fields in `errors`. A replay is not asked them again. The client generates the UUID `id`: resending it with the same terms answers 200 with the same body; with other terms, or an id another document holds, 409 purchase_debit_note_id_conflict. The client also generates each line `id`: one that a line of any other document already holds answers 409 purchase_debit_note_line_id_conflict. Requires `backoffice.purchases.debit-notes.create`.", "operationId": "registerPurchasesDebitNote", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "id", "origin_purchases_invoice_id", "emission_date", "reason", "lines" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "0199a000-0000-7000-8000-0000000004a1" }, "origin_purchases_invoice_id": { "description": "The approved regular purchases invoice this note raises.", "type": "string", "format": "uuid", "example": "0199a000-0000-7000-8000-0000000000a1" }, "emission_date": { "description": "On or after the origin's emission date and no later than the company's today.", "type": "string", "format": "date", "example": "2026-09-30" }, "reason": { "type": "string", "example": "price_correction", "enum": [ "interest", "freight", "price_correction", "quantity_correction", "other" ] }, "observations": { "description": "A free explanation of the reason.", "type": "string", "nullable": true }, "provider_invoice_number": { "description": "The note's own printed number, kept as printed like an invoice's. Blank means absent.", "type": "string", "example": "ND-000123", "nullable": true, "maxLength": 60 }, "control_number": { "description": "The note's own fiscal control number, kept as printed like provider_invoice_number.", "type": "string", "example": "00-000456", "nullable": true, "maxLength": 60 }, "captured_amounts": { "description": "The statutory base and tax per tax group of the note, one per tax and rate.", "type": "array", "items": { "$ref": "#/components/schemas/PurchasesCapturedAmountInput" }, "nullable": true }, "lines": { "description": "Line ids are distinct, and each origin line is raised once.", "type": "array", "items": { "$ref": "#/components/schemas/PurchasesDebitNoteLineInput" }, "minItems": 1 } }, "type": "object" } } } }, "responses": { "201": { "description": "Debit note registered as a draft", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchasesDebitNoteRegistered" } } } }, "200": { "description": "The same id was already registered with the same terms; nothing was written", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchasesDebitNoteRegistered" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks backoffice.purchases.debit-notes.create" }, "404": { "description": "The company was not found" }, "409": { "description": "purchase_debit_note_id_conflict: the id is already used with other terms or by another document; purchase_debit_note_line_id_conflict: a line id is already used by a line of another document; or purchases_invoice_provider_number_already_registered, which also carries existing_code and existing_kind (see PurchasesDocumentProviderNumberConflict)", "content": { "application/json": { "schema": { "required": [ "title", "status", "detail", "error_code" ], "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "detail": { "type": "string" }, "error_code": { "type": "string", "enum": [ "purchase_debit_note_id_conflict", "purchase_debit_note_line_id_conflict", "purchases_invoice_provider_number_already_registered" ] }, "existing_code": { "description": "Only on purchases_invoice_provider_number_already_registered: the code of the document that holds the number, empty when it cannot be named.", "type": "string", "example": "NDP2600001" }, "existing_kind": { "description": "Only on purchases_invoice_provider_number_already_registered: the kind of that document, null exactly when existing_code is empty.", "type": "string", "nullable": true, "enum": [ "regular", "opening", "credit_note", "debit_note" ] } }, "type": "object" } } } }, "422": { "description": "Validation error (`errors`); a refused origin (purchase_note_invalid_origin with its `cause`, see PurchasesNoteInvalidOrigin); a date before the origin (purchase_debit_note_emission_date_precedes_origin); refused lines (purchase_debit_note_without_lines, purchase_debit_note_line_repeated, purchase_debit_note_origin_line_repeated, purchase_debit_note_origin_line_not_found, purchase_debit_note_line_increase_not_positive, purchase_debit_note_line_without_amount, purchase_debit_note_linked_increase_without_increase, purchase_debit_note_new_concept_tax_not_in_origin, purchase_debit_note_line_type_unknown); invalid_purchase_debit_note_reason; invalid_provider_invoice_number or invalid_control_number; purchases_note_registration_incomplete under the Fiscal Profile guards, whose `errors` holds only the missing ones of provider_invoice_number, control_number and captured_amounts; purchases_invoice_captured_amounts_group_mismatch or an invalid capture; purchases_invoice_total_exceeds_storage. A New Concept reference the company cannot bind answers `{error: purchases_invoice_references_not_bindable, detail, violations}`, and an emission date after the company's today `{error: purchases_invoice_registration_date_out_of_range, detail, field}`.", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string" }, "error_code": { "type": "string", "example": "purchase_debit_note_new_concept_tax_not_in_origin", "nullable": true }, "cause": { "description": "Only on purchase_note_invalid_origin.", "type": "string", "enum": [ "not_found", "opening", "not_approved", "cancelled", "is_a_note" ] }, "errors": { "description": "The offending request fields, each with its messages.", "type": "object", "nullable": true }, "error": { "description": "Only on a globally rendered refusal: purchases_invoice_references_not_bindable or purchases_invoice_registration_date_out_of_range.", "type": "string" }, "field": { "description": "Only on purchases_invoice_registration_date_out_of_range.", "type": "string" }, "violations": { "description": "Only on purchases_invoice_references_not_bindable.", "type": "array", "items": { "type": "object" } } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/orders/{id}/approve": { "put": { "tags": [ "Backoffice - Orders" ], "summary": "Approve an Order (pedido interno)", "description": "Moves a por_aprobar Order to en_cotizacion.", "operationId": "d78982239234ae36891e0a339d9b4c32", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Order (pedido interno) approved. The body is an empty JSON object; read the Order with GET /api/backoffice/{tenant}/purchases/orders/{id}.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "The Order is not por_aprobar (OrderProblem).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderProblem" } } } }, "401": { "description": "Unauthenticated. The body carries `message`." }, "403": { "description": "Missing backoffice.purchases.orders.approve, no access to or membership in the company, or an API key without the write ability" }, "404": { "description": "No Order (pedido interno) with this id (OrderProblem), an unknown company in the path, or an API key bound to another company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderProblem" } } } }, "409": { "description": "Email address not verified" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/orders/{id}/cancel": { "put": { "tags": [ "Backoffice - Orders" ], "summary": "Cancel an Order (pedido interno)", "operationId": "1ab9cdbdd32c9c40139ae4cda29d32bc", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Order (pedido interno) cancelled. The body is an empty JSON object; read the Order with GET /api/backoffice/{tenant}/purchases/orders/{id}.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "The Order's status does not allow cancelling; only por_aprobar and en_cotizacion Orders can be cancelled (OrderProblem).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderProblem" } } } }, "401": { "description": "Unauthenticated. The body carries `message`." }, "403": { "description": "Missing backoffice.purchases.orders.cancel, no access to or membership in the company, or an API key without the write ability" }, "404": { "description": "No Order (pedido interno) with this id (OrderProblem), an unknown company in the path, or an API key bound to another company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderProblem" } } } }, "409": { "description": "Email address not verified" }, "422": { "description": "The Order is parcial and live linked Purchase Orders exist; purchase_orders[] lists them.", "content": { "application/json": { "schema": { "required": [ "error", "detail", "purchase_orders" ], "properties": { "error": { "type": "string", "example": "order_has_linked_purchase_orders" }, "detail": { "type": "string" }, "purchase_orders": { "type": "array", "items": { "required": [ "id", "code", "status" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "status": { "type": "string" } }, "type": "object" } } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/orders/{id}": { "get": { "tags": [ "Backoffice - Orders" ], "summary": "Show an Order (pedido interno) with its lines and linked Purchase Orders", "operationId": "687d46204415dd1d702168bfd4d4ae3f", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The Order (pedido interno). Quantities are decimal strings with four fractional digits.", "content": { "application/json": { "schema": { "required": [ "order" ], "properties": { "order": { "required": [ "id", "code", "reference", "date", "due_date", "status", "status_label", "company_id", "accounting_center_id", "accounting_center_name", "location_id", "location_name", "responsible_user_id", "responsible_user_name", "department_id", "department_name", "observations", "created_by", "created_by_name", "created_at", "updated_at", "can_be_modified", "can_be_cancelled", "total_quantity", "total_used_quantity", "remaining_quantity", "labels", "items", "purchase_orders" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string", "example": "PED2024001" }, "reference": { "type": "string" }, "date": { "type": "string", "format": "date", "example": "2026-01-15" }, "due_date": { "type": "string", "format": "date", "example": "2026-01-31", "nullable": true }, "status": { "type": "string", "enum": [ "por_aprobar", "en_cotizacion", "parcial", "procesado", "anulado" ] }, "status_label": { "type": "string", "example": "Por Aprobar" }, "company_id": { "type": "string", "format": "uuid" }, "accounting_center_id": { "type": "string", "format": "uuid" }, "accounting_center_name": { "type": "string", "nullable": true }, "location_id": { "type": "string", "format": "uuid" }, "location_name": { "type": "string", "nullable": true }, "responsible_user_id": { "description": "User ids are not UUIDs.", "type": "string" }, "responsible_user_name": { "type": "string", "nullable": true }, "department_id": { "type": "string", "nullable": true }, "department_name": { "type": "string", "nullable": true }, "observations": { "description": "Empty string when the Order has no observations.", "type": "string" }, "created_by": { "description": "User ids are not UUIDs.", "type": "string" }, "created_by_name": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "nullable": true }, "updated_at": { "type": "string", "format": "date-time", "nullable": true }, "can_be_modified": { "type": "boolean" }, "can_be_cancelled": { "type": "boolean" }, "total_quantity": { "type": "string", "example": "3.0000" }, "total_used_quantity": { "type": "string", "example": "0.0000" }, "remaining_quantity": { "type": "string", "example": "3.0000" }, "labels": { "type": "array", "items": { "required": [ "id", "name", "tone", "archived" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "tone": { "type": "string" }, "archived": { "type": "boolean" } }, "type": "object" } }, "items": { "type": "array", "items": { "required": [ "id", "item_id", "item_name", "category_id", "category_name", "quantity", "used_quantity", "remaining_quantity", "unit_id", "unit_name", "accounting_center_id", "accounting_center_name", "accounting_account_id", "location_id", "location_name", "project_id", "manager_id", "manager_name", "comment", "attributes", "is_fully_used", "is_partially_used", "usage_percentage" ], "properties": { "id": { "type": "string", "format": "uuid" }, "item_id": { "type": "string", "format": "uuid" }, "item_name": { "type": "string", "nullable": true }, "category_id": { "type": "string", "format": "uuid" }, "category_name": { "type": "string", "nullable": true }, "quantity": { "type": "string", "example": "3.0000" }, "used_quantity": { "type": "string", "example": "0.0000" }, "remaining_quantity": { "type": "string", "example": "3.0000" }, "unit_id": { "type": "string", "format": "uuid" }, "unit_name": { "type": "string", "nullable": true }, "accounting_center_id": { "type": "string", "format": "uuid" }, "accounting_center_name": { "type": "string", "nullable": true }, "accounting_account_id": { "type": "string", "format": "uuid", "nullable": true }, "location_id": { "type": "string", "format": "uuid" }, "location_name": { "type": "string", "nullable": true }, "project_id": { "type": "string", "nullable": true }, "manager_id": { "type": "string", "nullable": true }, "manager_name": { "type": "string", "nullable": true }, "comment": { "type": "string", "nullable": true }, "attributes": { "type": "string", "nullable": true }, "is_fully_used": { "type": "boolean" }, "is_partially_used": { "type": "boolean" }, "usage_percentage": { "type": "number" } }, "type": "object" } }, "purchase_orders": { "type": "array", "items": { "required": [ "id", "code", "status", "emission_date", "provider_name", "total", "items" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "status": { "type": "string", "example": "to_be_invoiced" }, "emission_date": { "type": "string", "example": "2026-01-02" }, "provider_name": { "type": "string", "nullable": true }, "total": { "description": "Decimal string with two fractional digits.", "type": "string", "example": "99.90" }, "items": { "type": "array", "items": { "required": [ "order_item_id", "purchase_order_item_id", "quantity" ], "properties": { "order_item_id": { "type": "string", "nullable": true }, "purchase_order_item_id": { "type": "string" }, "quantity": { "type": "string", "example": "1.0000" } }, "type": "object" } } }, "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "No Order (pedido interno) with this id in the company (error_code `order_not_found`, title/status/detail envelope)" }, "401": { "description": "Unauthenticated. The body carries `message`." }, "403": { "description": "Missing backoffice.purchases.orders.view, no access to or membership in the company" }, "404": { "description": "No Order (pedido interno) with this id in the company (OrderProblem), an unknown company in the path, or an API key bound to another company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderProblem" } } } }, "409": { "description": "Email address not verified" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Backoffice - Orders" ], "summary": "Update an Order (pedido interno) while it is por_aprobar", "description": "Replaces the header and every line of the Order.", "operationId": "b08f484d47ae49b0519b1d131de2725b", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "reference", "date", "accounting_center_id", "location_id", "responsible_user_id", "items" ], "properties": { "reference": { "type": "string", "maxLength": 255 }, "date": { "description": "Deliberately narrowed to YYYY-MM-DD. The validator rule is Laravel's date and accepts looser inputs; the stored and returned value is a calendar date.", "type": "string", "format": "date", "example": "2026-01-15" }, "due_date": { "description": "On or after `date`. Narrowed to YYYY-MM-DD like `date`.", "type": "string", "format": "date", "example": "2026-01-31", "nullable": true }, "accounting_center_id": { "type": "string", "format": "uuid" }, "location_id": { "type": "string", "format": "uuid" }, "responsible_user_id": { "description": "User ids are not UUIDs.", "type": "string" }, "department_id": { "type": "string", "format": "uuid", "nullable": true }, "observations": { "type": "string", "nullable": true, "maxLength": 1000 }, "items": { "type": "array", "items": { "required": [ "item_id", "category_id", "quantity", "unit_id", "accounting_center_id", "accounting_account_id", "location_id" ], "properties": { "item_id": { "description": "Must reference an existing item of the company.", "type": "string", "format": "uuid" }, "category_id": { "description": "Must reference an existing item category of the company.", "type": "string", "format": "uuid" }, "quantity": { "description": "Number or decimal string, at least 0.0001. Stored at four decimal places; a value that is <= 0 at scale 4 is refused with 400 order_line_invalid_quantity. Decimal strings are deliberately narrowed to plain digits with an optional fraction; exponent, sign and leading-dot forms that the validator also accepts are not published.", "oneOf": [ { "type": "number", "example": 1.5, "minimum": 0.0001 }, { "type": "string", "pattern": "^(?!0+(?:\\.0+)?$)(?!0*\\.0000)\\d+(?:\\.\\d+)?$", "example": "1.5000" } ] }, "unit_id": { "description": "Must reference an existing unit of the company.", "type": "string", "format": "uuid" }, "accounting_center_id": { "description": "Must reference an existing accounting center of the company.", "type": "string", "format": "uuid" }, "accounting_account_id": { "description": "The key must be present; send null when the line has no accounting account. A value must reference an existing accounting account of the company.", "type": "string", "format": "uuid", "nullable": true }, "location_id": { "description": "Must reference an existing location of the company.", "type": "string", "format": "uuid" }, "project_id": { "type": "string", "nullable": true }, "manager_id": { "description": "Id of an existing user.", "type": "string", "nullable": true }, "comment": { "type": "string", "nullable": true, "maxLength": 500 }, "attributes": { "type": "string", "nullable": true } }, "type": "object" }, "minItems": 1 } }, "type": "object" } } } }, "responses": { "200": { "description": "Order (pedido interno) updated. The body is an empty JSON object; read the Order with GET /api/backoffice/{tenant}/purchases/orders/{id}.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "A line quantity is <= 0 at four decimal places (error_code `order_line_invalid_quantity`, title/status/detail envelope)" }, "401": { "description": "Unauthenticated. The body carries `message`." }, "403": { "description": "Missing backoffice.purchases.orders.update, no access to or membership in the company, or an API key without the write ability" }, "404": { "description": "No Order (pedido interno) with this id in the company (error_code `order_not_found`, title/status/detail envelope), an unknown company in the path, or an API key bound to another company" }, "409": { "description": "The Order is no longer por_aprobar (error_code `order_cannot_be_modified`, title/status/detail envelope), or the email address is not verified" }, "422": { "description": "Request validation failed (error_code null), or a line names a category other than its item's, or a unit not assigned to its item (error_code `purchase_line_item_mismatch`). The body is the title/status/detail envelope with `errors` keyed by field, e.g. items.0.item_id, items.0.category_id or items.0.unit_id. A line that keeps the (item, category) pair the Order already stores is accepted after the item moves to another category. Nothing is saved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/orders/export": { "get": { "tags": [ "Backoffice - Orders" ], "summary": "Export the Orders (pedidos internos) list to XLSX", "description": "Exports the orders matching the list filters, or exactly the orders named by ids[]. When ids[] is present and non-empty every other filter is ignored.", "operationId": "84ca10616bf83764e115367669cab634", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "ids[]", "in": "query", "description": "Exclusive selection of up to 500 order ids.", "schema": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 500 } }, { "name": "search", "in": "query", "schema": { "type": "string" } }, { "name": "date_from", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "date_to", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "department_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "description": "Scalar status or `all`. Prefer status[] for multi-value filters.", "schema": { "type": "string", "enum": [ "por_aprobar", "en_cotizacion", "parcial", "procesado", "anulado", "all" ] } }, { "name": "status[]", "in": "query", "description": "Repeated status filter values (e.g. status[]=por_aprobar&status[]=parcial).", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "por_aprobar", "en_cotizacion", "parcial", "procesado", "anulado" ] } } }, { "name": "responsible_user_id", "in": "query", "description": "Scalar non-empty user id. Prefer responsible_user_id[] for multi-value filters.", "schema": { "type": "string", "minLength": 1 } }, { "name": "responsible_user_id[]", "in": "query", "description": "Repeated responsible user ids.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "location_id", "in": "query", "description": "Scalar location UUID. Prefer location_id[] for multi-value filters.", "schema": { "type": "string", "format": "uuid" } }, { "name": "location_id[]", "in": "query", "description": "Repeated location UUIDs.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" } } }, { "name": "label_ids[]", "in": "query", "schema": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 20 } } ], "responses": { "200": { "description": "XLSX workbook. An empty match returns a header-only sheet.", "headers": { "Cache-Control": { "description": "Always no-store: the workbook is never cached", "schema": { "type": "string", "example": "no-store, private" } } }, "content": { "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Unauthenticated. The body carries `message`." }, "403": { "description": "Missing backoffice.purchases.orders.view, no access to or membership in the company" }, "404": { "description": "Unknown company in the path, or an API key bound to another company" }, "409": { "description": "Email address not verified" }, "422": { "description": "Invalid filter, more than 500 ids, or more than 5000 matching orders" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/orders": { "get": { "tags": [ "Backoffice - Orders" ], "summary": "List Orders (pedidos internos)", "description": "Paginated Orders (pedidos internos) of the company with per-status and per-label counts for the same filters.", "operationId": "4bc12add40fafc974194cc54cc3cdde7", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 15, "maximum": 100, "minimum": 1 } }, { "name": "search", "in": "query", "schema": { "type": "string" } }, { "name": "date_from", "in": "query", "description": "Deliberately narrowed to YYYY-MM-DD. The validator rule is Laravel's date, which accepts any strtotime value.", "schema": { "type": "string", "format": "date" } }, { "name": "date_to", "in": "query", "description": "Deliberately narrowed to YYYY-MM-DD. The validator rule is Laravel's date, which accepts any strtotime value.", "schema": { "type": "string", "format": "date" } }, { "name": "department_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "description": "Scalar status or `all`. Prefer status[] for multi-value filters.", "schema": { "type": "string", "enum": [ "por_aprobar", "en_cotizacion", "parcial", "procesado", "anulado", "all" ] } }, { "name": "status[]", "in": "query", "description": "Repeated status filter values (e.g. status[]=por_aprobar&status[]=parcial).", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "por_aprobar", "en_cotizacion", "parcial", "procesado", "anulado" ] } } }, { "name": "responsible_user_id", "in": "query", "description": "Scalar non-empty user id. User ids are not UUIDs. Prefer responsible_user_id[] for multi-value filters.", "schema": { "type": "string", "minLength": 1 } }, { "name": "responsible_user_id[]", "in": "query", "description": "Repeated responsible user ids.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "location_id", "in": "query", "description": "Scalar location UUID. Prefer location_id[] for multi-value filters.", "schema": { "type": "string", "format": "uuid" } }, { "name": "location_id[]", "in": "query", "description": "Repeated location UUIDs.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" } } }, { "name": "label_ids[]", "in": "query", "description": "Repeated label UUIDs, at most 20.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 20 } }, { "name": "sort_field", "in": "query", "schema": { "type": "string", "default": "created_at", "enum": [ "date", "code", "created_at" ] } }, { "name": "sort_direction", "in": "query", "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } }, { "name": "group_by", "in": "query", "schema": { "type": "string", "enum": [ "status" ] } } ], "responses": { "200": { "description": "One page of Orders (pedidos internos). The pagination keys keep their camelCase names.", "content": { "application/json": { "schema": { "required": [ "orders", "total", "perPage", "currentPage", "lastPage", "meta" ], "properties": { "orders": { "type": "array", "items": { "required": [ "id", "code", "reference", "date", "due_date", "status", "status_label", "location_id", "location_name", "responsible_user_id", "responsible_user_name", "department_id", "department_name", "accounting_center_id", "accounting_center_name", "observations", "created_by", "created_by_name", "created_at", "updated_at", "items_count", "total_quantity", "total_used_quantity", "remaining_quantity", "can_be_modified", "can_be_cancelled", "labels" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string", "example": "PED2024001" }, "reference": { "type": "string" }, "date": { "type": "string", "format": "date-time", "example": "2026-01-01T00:00:00.000000Z" }, "due_date": { "type": "string", "format": "date-time", "nullable": true }, "status": { "type": "string", "enum": [ "por_aprobar", "en_cotizacion", "parcial", "procesado", "anulado" ] }, "status_label": { "type": "string", "example": "Por Aprobar" }, "location_id": { "type": "string", "format": "uuid" }, "location_name": { "type": "string", "nullable": true }, "responsible_user_id": { "description": "User ids are not UUIDs.", "type": "string" }, "responsible_user_name": { "type": "string", "nullable": true }, "department_id": { "type": "string", "nullable": true }, "department_name": { "type": "string", "nullable": true }, "accounting_center_id": { "type": "string", "format": "uuid" }, "accounting_center_name": { "type": "string", "nullable": true }, "observations": { "type": "string", "nullable": true }, "created_by": { "description": "User ids are not UUIDs.", "type": "string" }, "created_by_name": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "nullable": true }, "updated_at": { "type": "string", "format": "date-time", "nullable": true }, "items_count": { "type": "integer" }, "total_quantity": { "type": "number" }, "total_used_quantity": { "type": "number" }, "remaining_quantity": { "type": "number" }, "can_be_modified": { "type": "boolean" }, "can_be_cancelled": { "type": "boolean" }, "labels": { "type": "array", "items": { "required": [ "id", "name", "tone", "archived" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "tone": { "type": "string" }, "archived": { "type": "boolean" } }, "type": "object" } } }, "type": "object" } }, "total": { "type": "integer" }, "perPage": { "type": "integer" }, "currentPage": { "type": "integer" }, "lastPage": { "type": "integer" }, "meta": { "required": [ "counts", "label_counts" ], "properties": { "counts": { "description": "Orders per status for the same filters, ignoring the status filter.", "required": [ "por_aprobar", "en_cotizacion", "parcial", "procesado", "anulado" ], "properties": { "por_aprobar": { "type": "integer" }, "en_cotizacion": { "type": "integer" }, "parcial": { "type": "integer" }, "procesado": { "type": "integer" }, "anulado": { "type": "integer" } }, "type": "object" }, "label_counts": { "description": "Orders per label id for the same filters, ignoring label_ids[]. No counts serialize as an empty JSON array, not an object.", "oneOf": [ { "type": "object", "additionalProperties": { "type": "integer" } }, { "type": "array", "items": { "type": "integer" }, "maxItems": 0 } ] } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated. The body carries `message`." }, "403": { "description": "Missing backoffice.purchases.orders.view, no access to or membership in the company" }, "404": { "description": "Unknown company in the path, or an API key bound to another company" }, "409": { "description": "Email address not verified" }, "422": { "description": "Invalid query parameter. The body is the title/status/detail envelope with `errors` keyed by parameter." }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Orders" ], "summary": "Create an Order (pedido interno) with a client-supplied id", "operationId": "8da3bf0077bb9fb19a1e976247d45cf3", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "id", "reference", "date", "accounting_center_id", "location_id", "responsible_user_id", "items" ], "properties": { "id": { "description": "Client-supplied Order id. It is the only identifier the client can predict, and the one to read the Order back with.", "type": "string", "format": "uuid" }, "reference": { "type": "string", "maxLength": 255 }, "date": { "description": "Deliberately narrowed to YYYY-MM-DD. The validator rule is Laravel's date and accepts looser inputs; the stored and returned value is a calendar date.", "type": "string", "format": "date", "example": "2026-01-15" }, "due_date": { "description": "On or after `date`. Narrowed to YYYY-MM-DD like `date`.", "type": "string", "format": "date", "example": "2026-01-31", "nullable": true }, "accounting_center_id": { "description": "Must reference an existing accounting center.", "type": "string", "format": "uuid" }, "location_id": { "description": "Must reference an existing location.", "type": "string", "format": "uuid" }, "responsible_user_id": { "description": "Id of an existing user. User ids are not UUIDs.", "type": "string" }, "department_id": { "type": "string", "nullable": true }, "observations": { "type": "string", "nullable": true, "maxLength": 1000 }, "items": { "type": "array", "items": { "required": [ "item_id", "category_id", "quantity", "unit_id", "accounting_center_id", "accounting_account_id", "location_id" ], "properties": { "item_id": { "description": "Must reference an existing item.", "type": "string", "format": "uuid" }, "category_id": { "description": "Must reference an existing item category.", "type": "string", "format": "uuid" }, "quantity": { "description": "Number or decimal string, at least 0.0001. Decimal strings are deliberately narrowed to plain digits with an optional fraction; exponent, sign and leading-dot forms that the validator also accepts are not published.", "oneOf": [ { "type": "number", "example": 1.5, "minimum": 0.0001 }, { "type": "string", "pattern": "^(?!0+(?:\\.0+)?$)(?!0*\\.0000)\\d+(?:\\.\\d+)?$", "example": "1.5000" } ] }, "unit_id": { "description": "Must reference an existing unit.", "type": "string", "format": "uuid" }, "accounting_center_id": { "description": "Must reference an existing accounting center.", "type": "string", "format": "uuid" }, "accounting_account_id": { "description": "The key must be present; send null when the line has no accounting account. A value must reference an existing accounting account.", "type": "string", "format": "uuid", "nullable": true }, "location_id": { "description": "Must reference an existing location.", "type": "string", "format": "uuid" }, "project_id": { "type": "string", "nullable": true }, "manager_id": { "description": "Id of an existing user.", "type": "string", "nullable": true }, "comment": { "type": "string", "nullable": true, "maxLength": 500 }, "attributes": { "type": "string", "nullable": true } }, "type": "object" }, "minItems": 1 } }, "type": "object" } } } }, "responses": { "201": { "description": "Order (pedido interno) created. The body is an empty JSON object and carries no identifier; read the Order with GET /api/backoffice/{tenant}/purchases/orders/{id} using the client-supplied id.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthenticated. The body carries `message`." }, "403": { "description": "Missing backoffice.purchases.orders.create, no access to or membership in the company, or an API key without the write ability" }, "404": { "description": "Unknown company in the path, or an API key bound to another company" }, "409": { "description": "An Order with this id already exists (error_code `order_already_exists`, title/status/detail envelope), or the email address is not verified" }, "422": { "description": "Request validation failed: the body carries `message` and `errors` keyed by field, e.g. items.0.accounting_account_id (OrderRequestValidation). Or a line names a category other than its item's, or a unit not assigned to its item: an OrderProblem with error_code `purchase_line_item_mismatch` and `errors` keyed by the refused line field, e.g. items.0.category_id or items.0.unit_id. Nothing is created.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/OrderRequestValidation" }, { "$ref": "#/components/schemas/OrderProblem" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/orders/{id}/responsible": { "put": { "tags": [ "Backoffice - Orders" ], "summary": "Reassign the responsible user of an Order (pedido interno)", "operationId": "4bf408f649353a3c54a4efbab0e17888", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "responsible_user_id" ], "properties": { "responsible_user_id": { "description": "Company user id that becomes the Order Responsable", "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "description": "Responsible reassigned. The body is an empty JSON object; read the Order with GET /api/backoffice/{tenant}/purchases/orders/{id}.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthenticated. The body carries `message`." }, "403": { "description": "Missing backoffice.purchases.orders.update, no access to or membership in the company, or an API key without the write ability" }, "404": { "description": "No Order (pedido interno) with this id (error_code `order_not_found`, title/status/detail envelope), an unknown company in the path, or an API key bound to another company" }, "409": { "description": "The responsible cannot be reassigned in the Order's current status (error_code `order_responsible_cannot_be_reassigned`, title/status/detail envelope), or the email address is not verified" }, "422": { "description": "Validation error" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/payables/aging/export": { "get": { "tags": [ "Purchases Payables" ], "summary": "Exportar antigüedad de cuentas por pagar", "operationId": "cd7fce2b372fa16d52c2b8adee13d0be", "parameters": [ { "name": "tenant", "in": "path", "description": "Company UUID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/PayablesAgingProvider" }, { "$ref": "#/components/parameters/PayablesAgingCurrency" }, { "$ref": "#/components/parameters/PayablesAgingCenter" } ], "responses": { "200": { "description": "Numeric XLSX attachment antiguedad_cxp_{as_of}.xlsx with the JSON rows, currency totals and book totals when every absolute amount is at most 9999999999999.99 and serialization preserves cents; otherwise 422", "headers": { "Cache-Control": { "description": "Always no-store: the workbook is never cached", "schema": { "type": "string", "example": "no-store, private" } } }, "content": { "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Unauthenticated before controller execution", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayablesAgingMessageError" } } } }, "403": { "description": "Payables permission or tenant membership denied", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/PayablesAgingForbiddenError" }, { "$ref": "#/components/schemas/PayablesAgingProblem" } ] } } } }, "404": { "description": "An unknown company in the path, answered by the tenant middleware with a message, or company_not_found when the report cannot read the company's record", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PayablesAgingMessageError" }, { "$ref": "#/components/schemas/PayablesAgingProblem" } ] } } } }, "422": { "description": "FormRequest validation of a malformed or foreign provider or accounting center, or a currency outside the enum; invalid_currency from the domain as a fallback; unsafe numeric XLSX amounts return payables_aging_excel_precision_exceeded before any attachment", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PayablesAgingValidationError" }, { "$ref": "#/components/schemas/PayablesAgingProblem" } ] } } } }, "503": { "description": "payables_aging_query_failed: the aging query is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayablesAgingProblem" } } } }, "500": { "description": "payables_aging_invalid_data, an unexpected internal failure, or a tenant route that lost its company (TenantCompanyMissing)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayablesAgingProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/payables/aging": { "get": { "tags": [ "Purchases Payables" ], "summary": "Antigüedad de cuentas por pagar", "operationId": "83dd90616fff46365b7c2b94e733c1ae", "parameters": [ { "name": "tenant", "in": "path", "description": "Company UUID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/PayablesAgingProvider" }, { "$ref": "#/components/parameters/PayablesAgingCurrency" }, { "$ref": "#/components/parameters/PayablesAgingCenter" } ], "responses": { "200": { "description": "Exact decimal aging as of today; empty rows and 0.00 totals when nothing is open", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayablesAging" } } } }, "401": { "description": "Unauthenticated before controller execution", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayablesAgingMessageError" } } } }, "403": { "description": "Payables permission or tenant membership denied", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/PayablesAgingForbiddenError" }, { "$ref": "#/components/schemas/PayablesAgingProblem" } ] } } } }, "404": { "description": "An unknown company in the path, answered by the tenant middleware with a message, or company_not_found when the report cannot read the company's record", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PayablesAgingMessageError" }, { "$ref": "#/components/schemas/PayablesAgingProblem" } ] } } } }, "422": { "description": "FormRequest validation of a malformed or foreign provider or accounting center, or a currency outside the enum; invalid_currency from the domain as a fallback", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PayablesAgingValidationError" }, { "$ref": "#/components/schemas/PayablesAgingProblem" } ] } } } }, "503": { "description": "payables_aging_query_failed: the aging query is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayablesAgingProblem" } } } }, "500": { "description": "payables_aging_invalid_data, an unexpected internal failure, or a tenant route that lost its company (TenantCompanyMissing)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayablesAgingProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/providers/{id}/statement/export": { "get": { "tags": [ "Purchases Payables" ], "summary": "Exportar estado de cuenta del proveedor", "operationId": "c2f8f0c58c88bdfbd5dcf7783458ed7f", "parameters": [ { "name": "tenant", "in": "path", "description": "Company UUID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "Provider UUID belonging to the tenant", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/ProviderStatementFrom" }, { "$ref": "#/components/parameters/ProviderStatementTo" }, { "$ref": "#/components/parameters/ProviderStatementCurrency" } ], "responses": { "200": { "description": "Numeric XLSX attachment estado_cuenta_{provider code}_{from}_{to}.xlsx titled as an informational document, with the JSON sections and lines under the amount headings Aumento, Disminución and Saldo por pagar, when every absolute amount is at most 9999999999999.99 and serialization preserves cents; otherwise 422", "headers": { "Cache-Control": { "description": "Always no-store: the workbook is never cached", "schema": { "type": "string", "example": "no-store, private" } } }, "content": { "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Unauthenticated before controller execution", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderStatementMessageError" } } } }, "403": { "description": "Payables permission or tenant membership denied", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ProviderStatementForbiddenError" }, { "$ref": "#/components/schemas/ProviderStatementProblem" } ] } } } }, "404": { "description": "Tenant middleware or controller company not found; provider_not_found for an unknown provider or a provider of another company", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProviderStatementMessageError" }, { "$ref": "#/components/schemas/ProviderStatementProblem" } ] } } } }, "422": { "description": "FormRequest validation of a malformed provider id, a missing or malformed from or to, a to before from, or a currency outside the enum; provider_statement_invalid_period and invalid_currency from the domain as fallbacks; unsafe numeric XLSX amounts return provider_statement_excel_precision_exceeded before any attachment", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProviderStatementValidationError" }, { "$ref": "#/components/schemas/ProviderStatementProblem" } ] } } } }, "503": { "description": "provider_statement_query_failed: the statement query is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderStatementProblem" } } } }, "500": { "description": "provider_statement_invalid_data or an unexpected internal failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderStatementProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/providers/{id}/statement": { "get": { "tags": [ "Purchases Payables" ], "summary": "Estado de cuenta del proveedor", "operationId": "95ab33f8b16dd89b14715f269b09402d", "parameters": [ { "name": "tenant", "in": "path", "description": "Company UUID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "Provider UUID belonging to the tenant", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/ProviderStatementFrom" }, { "$ref": "#/components/parameters/ProviderStatementTo" }, { "$ref": "#/components/parameters/ProviderStatementCurrency" } ], "responses": { "200": { "description": "Exact decimal statement; no sections when the provider has no movement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderStatement" } } } }, "401": { "description": "Unauthenticated before controller execution", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderStatementMessageError" } } } }, "403": { "description": "Payables permission or tenant membership denied", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ProviderStatementForbiddenError" }, { "$ref": "#/components/schemas/ProviderStatementProblem" } ] } } } }, "404": { "description": "Tenant middleware or controller company not found; provider_not_found for an unknown provider or a provider of another company", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProviderStatementMessageError" }, { "$ref": "#/components/schemas/ProviderStatementProblem" } ] } } } }, "422": { "description": "FormRequest validation of a malformed provider id, a missing or malformed from or to, a to before from, or a currency outside the enum; provider_statement_invalid_period and invalid_currency from the domain as fallbacks", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProviderStatementValidationError" }, { "$ref": "#/components/schemas/ProviderStatementProblem" } ] } } } }, "503": { "description": "provider_statement_query_failed: the statement query is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderStatementProblem" } } } }, "500": { "description": "provider_statement_invalid_data or an unexpected internal failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderStatementProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/payment-views": { "get": { "tags": [ "Backoffice - Payment Views" ], "summary": "Search payment views with provider information", "operationId": "8b7677029caeee475f3ef8bf7322857c", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "provider_id", "in": "query", "description": "Scalar UUID or repeated provider_id[] values", "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Scalar status or repeated status[] values", "schema": { "type": "string" } }, { "name": "kind", "in": "query", "description": "One kind. To match several, send kind[] (MER-3640).", "schema": { "type": "string", "enum": [ "settlement", "advance" ] } }, { "name": "kind[]", "in": "query", "description": "Nonempty list; OR within the field, AND with other filters (MER-3640).", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "settlement", "advance" ] }, "minItems": 1 } }, { "name": "responsible_user_id", "in": "query", "description": "Scalar id or repeated responsible_user_id[] values", "schema": { "type": "string" } }, { "name": "label_ids", "in": "query", "description": "Filter by assigned label ids", "schema": { "type": "array", "items": { "type": "string", "format": "uuid" } } }, { "name": "code", "in": "query", "description": "Search by payment code", "schema": { "type": "string" } }, { "name": "search", "in": "query", "description": "General search in payment code", "schema": { "type": "string" } }, { "name": "date_from", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "date_to", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "invoice_id", "in": "query", "description": "Filter payments by invoice ID (single UUID or array of UUIDs)", "schema": { "oneOf": [ { "type": "string", "format": "uuid" }, { "type": "array", "items": { "type": "string", "format": "uuid" } } ] } }, { "name": "purchase_contract_id", "in": "query", "description": "Filter by the Purchase Contract whose automation produced the payment", "schema": { "type": "string", "format": "uuid" } }, { "name": "auto_approved", "in": "query", "description": "True returns only payments the contract automation advanced past human approval; false returns every payment it did not — including ones still awaiting approval and auto-generated ones deliberately stopped at the to_be_approved ceiling. Combine with status to narrow further.", "schema": { "type": "boolean" } }, { "name": "auto_approved_from", "in": "query", "description": "Inclusive lower bound of the auto-approval period", "schema": { "type": "string", "format": "date" } }, { "name": "auto_approved_to", "in": "query", "description": "Inclusive upper bound of the auto-approval period; a bare date covers the whole day", "schema": { "type": "string", "format": "date" } }, { "name": "ids", "in": "query", "description": "Filter by specific payment IDs", "schema": { "type": "array", "items": { "type": "string", "format": "uuid" } } }, { "name": "sort_by", "in": "query", "description": "One of id, code, date_payment, provider_id, amount_paid, date_payment_applied, status, company_id, purchase_contract_id, auto_approved_at or created_at; any other value sorts by the default column.", "schema": { "type": "string", "default": "code" } }, { "name": "sort_order", "in": "query", "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 20 } } ], "responses": { "200": { "description": "List of payment views with provider information", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "required": [ "id", "code", "starter", "date_payment", "provider_id", "provider_name", "amount_paid", "kind", "currency", "balance", "functional_balance", "reporting_balance", "document_currency", "date_payment_applied", "status", "instrument_names", "company_id", "invoice_codes", "invoices_count", "purchase_contract_id", "auto_approved_at", "responsible_user_id", "responsible_user_name", "labels" ], "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "starter": { "description": "The invoice or provider the payment was started from; both empty when the stored starter cannot be read.", "required": [ "id", "type" ], "properties": { "id": { "type": "string" }, "type": { "type": "string", "example": "invoice" } }, "type": "object" }, "provider_id": { "type": "string" }, "provider_name": { "type": "string" }, "date_payment": { "type": "string", "format": "date" }, "date_payment_applied": { "description": "When the payment was applied; null until then.", "type": "string", "format": "date", "nullable": true }, "company_id": { "type": "string" }, "invoice_codes": { "description": "The codes of up to three regular or opening invoices the payment pays, comma-separated in code order (never a supplier note, ADR 0216); null when it pays none.", "type": "string", "example": "PIN0000001, PIN0000002", "nullable": true }, "invoices_count": { "description": "How many distinct documents the payment's payables pay.", "type": "integer", "example": 2 }, "kind": { "type": "string", "enum": [ "settlement", "advance" ] }, "currency": { "description": "Advance currency, or the resolved document currency of a settlement.", "type": "string" }, "balance": { "description": "Advance units available after payout; zero before payout or after cancellation. Null for settlements.", "type": "string", "nullable": true }, "functional_balance": { "type": "string", "nullable": true }, "reporting_balance": { "type": "string", "nullable": true }, "amount_paid": { "type": "string", "example": "1000.00" }, "document_currency": { "description": "The Document Currency amount_paid is stated in (ISO 4217; USD or VES today): the currency the payment's payables stored when it was applied, else the one currency of the invoices it pays, else the company's functional currency; the advance currency for advances. Never null.", "type": "string", "example": "USD" }, "status": { "type": "string" }, "instrument_names": { "description": "The payment instruments of the method lines, distinct, in line order; empty when no line has an instrument.", "type": "array", "items": { "type": "string" } }, "responsible_user_id": { "type": "string", "nullable": true }, "responsible_user_name": { "type": "string", "nullable": true }, "labels": { "type": "array", "items": { "type": "object" } }, "purchase_contract_id": { "description": "Originating Purchase Contract, when this payment was auto-generated from its invoice", "type": "string", "format": "uuid", "nullable": true }, "auto_approved_at": { "description": "When the nightly generator advanced this payment past human approval; null when a human approved it, and also when the automation created the payment but deliberately left it awaiting one", "type": "string", "format": "date-time", "nullable": true } }, "type": "object" } }, "meta": { "properties": { "total": { "type": "integer" }, "per_page": { "type": "integer" }, "current_page": { "type": "integer" }, "counts": { "type": "object" }, "kind_counts": { "description": "Ignores only kind; every other filter remains, status included (MER-3640).", "required": [ "settlement", "advance" ], "properties": { "settlement": { "type": "integer" }, "advance": { "type": "integer" } }, "type": "object" }, "label_counts": { "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentProblem" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentProblem" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentMiddlewareError" } } } }, "404": { "description": "Unknown or inaccessible tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentMiddlewareError" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/payments/{id}/accounting-readiness": { "get": { "tags": [ "Backoffice - Payments" ], "summary": "Get accounting readiness for a payment", "description": "`ready` answers `missing` alone. While the payment awaits approval or application, `warnings` may carry OFFICIAL_RATE_STALE (subject_type payment_method, against the first instrument of each currency, details `[pair, last value date]`) when the official rate a line would take if the payment were applied today is stale: approving never waits for it, applying today answers 422 until a fresh or manual rate is loaded.", "operationId": "067b98a6f74c3f4195a6edd464c64f60", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Accounting readiness snapshot", "content": { "application/json": { "schema": { "properties": { "ready": { "type": "boolean" }, "missing": { "type": "array", "items": { "properties": { "reason_code": { "type": "string" }, "subject_type": { "type": "string" }, "subject_id": { "type": "string" }, "human_message": { "type": "string" }, "details": { "type": "array", "items": { "type": "string" } } }, "type": "object" } }, "warnings": { "$ref": "#/components/schemas/AccountingReadinessWarnings" } }, "type": "object" } } } }, "403": { "description": "Unauthorized" }, "404": { "description": "Payment not found" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/payments/{id}/apply": { "post": { "tags": [ "Backoffice - Purchases Payments" ], "summary": "Apply a payment", "description": "Applies an approved payment. An advance locks no invoices, freezes one snapshot per method currency at one registration instant, and stores the carrying treasury totals as its own balance before posting purchase_payment.advance_paid without payable or profit/loss lines. Today selects by publication instant; past dates select the first value date on or after the application date; future dates reject. Identity books need no official rate. A payment whose lines are all in the currency of its invoices applies what its payables state; one with a line in another currency derives the debt it settles on its only invoice from the units at the official rate of the application date (ADR 0199/0202): within one cent per converting line of the open balance it settles that balance exactly, with the cents as a rounding difference, and beyond it answers 422 derived_debt_exceeds_open_balance. Idempotent: applying a payment that is already applied answers 200 with the payment as it stands (its stored date_payment_applied; the one sent is ignored) and locks, settles, writes and posts nothing, so its invoices are relieved and its PURCHASE_PAYMENT_APPLIED entry posted once. A payment to be approved or cancelled answers 400 invalid_payment_status_transition.", "operationId": "b7d7e5bfebcd3f3ef6723d98e1a60037", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "date_payment_applied" ], "properties": { "date_payment_applied": { "type": "string", "format": "date", "example": "2023-01-15" } }, "type": "object" } } } }, "responses": { "200": { "description": "Payment applied: its whole settlement (each line's Rate Snapshot, the treasury relief and the differences by cause; each payable's debt settled and Relieved Amounts) is stored and each invoice relieves its three balances, in one transaction. Also the answer for a payment that was already applied, which is answered as it stands with nothing written.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentApplyResult" } } } }, "400": { "description": "invalid_payment_status_transition (a payment to be approved or cancelled; the detail names both statuses), or an invoice already fully paid (invoice_already_fully_paid) or, for a payment whose lines are all in the currency of its invoices, a payable above the invoice balance (payment_exceeds_invoice_balance); the two invoice refusals name the invoice's currency and add its figures (see PaymentInvoiceBalanceProblem)", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/PaymentProblem" }, { "$ref": "#/components/schemas/PaymentInvoiceBalanceProblem" } ] } } } }, "422": { "description": "Validation refuses a missing or unparseable `date_payment_applied`: `errors.date_payment_applied` names it and `error_code` is null. Otherwise the payment cannot be settled or posted today. `accounting_configuration_incomplete` with `missing[].reason_code` OFFICIAL_RATE_STALE (an application dated today while the official rate is stale) or OFFICIAL_RATE_NOT_AVAILABLE (a back-dated application without a rate of its value date), each against the payment method it values, or EXCHANGE_POSTING_ACCOUNT_MISSING against the company, with the realized exchange role a difference of the settlement needs (realized_exchange_gain or realized_exchange_loss) in `details`; or an `error_code` among cash_event_date_in_the_future, unsupported_cash_event_currency, derived_debt_exceeds_open_balance, derived_debt_does_not_match_applied_amounts (both add `derived`, `open`, `applied` and `currency`, see PaymentSettlementRejectionProblem), purchases_invoice_not_found, payment_settles_an_invoice_twice and payment_payable_not_payable (an invoice, opening or debit note of the payment is a draft or was cancelled; the payment stays to be applied); or payment_line_derives_no_debt: a method line's settling units derive less than one cent of the invoices' currency at the official rate of the application date, so the line would settle nothing; `errors` is null, `method_line` names the line (the approved payment's lines are frozen), the body adds `units`, `units_currency`, `currency` and `rate_basis` (see PaymentLineDerivesNoDebtProblem), no treasury position is locked and the payment stays to be applied; or `error_code` payment_method_instrument_treasury_account_inactive with Problem `reason` treasury_account_missing when a method line's position key has no treasury account (nothing is written).", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/PaymentAccountingConfigurationError" }, { "$ref": "#/components/schemas/PaymentProblem" }, { "$ref": "#/components/schemas/PaymentLineDerivesNoDebtProblem" }, { "$ref": "#/components/schemas/PaymentSettlementRejectionProblem" } ] } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentProblem" } } } }, "404": { "description": "Payment not found", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PaymentProblem" }, { "$ref": "#/components/schemas/PaymentMiddlewareError" } ] } } } }, "500": { "description": "The payment could not be persisted (error_code: payment_persistence_failed), or a stored settlement invariant broke, such as a method line stored without its currency (error_code: payment_method_currency_missing) or a settlement the ledger cannot post (error_code: purchase_payment_posting_unavailable, parallel_currency_conversion_error)" }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentMiddlewareError" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/payments/{id}/approve": { "post": { "tags": [ "Backoffice - Purchases Payments" ], "summary": "Approve a payment", "description": "Idempotent: approving a payment already approved (to_be_applied) answers 200 and checks, writes, records and publishes nothing; applied or cancelled answers 400 invalid_payment_status_transition.", "operationId": "ce5ffa549b92652817edcefd406080fc", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The payment is approved, or was already approved with nothing written" }, "400": { "description": "invalid_payment_status_transition: the payment is applied or cancelled; the detail names both statuses.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentProblem" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentProblem" } } } }, "404": { "description": "Payment not found", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PaymentProblem" }, { "$ref": "#/components/schemas/PaymentMiddlewareError" } ] } } } }, "500": { "description": "The payment could not be persisted (error_code: payment_persistence_failed)" }, "422": { "description": "Accounting readiness failure; supplier advances require the supplier_advances role, its active asset account and center, method accounts and parallel-flow support. Rates warn at approval and are enforced at payout; realized exchange roles are not required for advances. Or the payment is a supplier advance whose provider was deactivated since it was registered: a PaymentProblem with error_code purchases_provider_inactive and `errors.provider_id`, checked before readiness (MER-5279); a settlement never checks it.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PaymentAccountingConfigurationError" }, { "$ref": "#/components/schemas/PaymentProblem" } ] } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentMiddlewareError" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/payments/bulk-apply": { "post": { "tags": [ "Backoffice - Purchases Payments" ], "summary": "Bulk apply payments", "description": "Applies each payment once, by ascending id, each in its own savepoint: an item that cannot be applied is reported in `failures[]` with nothing of it written, and the others still apply. The date every item is applied on is checked first: a date after the company today refuses the whole batch with 422 before any payment is read, so no item is applied, not even a payment already applied.", "operationId": "c10743896813a3acb2bb216f745cc54a", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "ids", "date_payment_applied" ], "properties": { "ids": { "description": "Array of payment IDs to apply", "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1 }, "date_payment_applied": { "description": "Date when payments are applied, no later than the company today. Published as `format: date` on purpose: the validator accepts any date Laravel parses, but the API stores and answers the calendar day.", "type": "string", "format": "date" } }, "type": "object" } } } }, "responses": { "200": { "description": "Bulk apply completed. A payment already applied counts in success_count with no effects: nothing is written or posted for it again.", "content": { "application/json": { "schema": { "properties": { "success_count": { "type": "integer" }, "failed_count": { "type": "integer" }, "failures": { "type": "array", "items": { "required": [ "payment_id", "payment_code", "error", "error_code" ], "properties": { "payment_id": { "type": "string" }, "payment_code": { "type": "string" }, "error": { "description": "Why this item was not applied; nothing of it was written. A blocked official rate reads as its readiness message, e.g. «La tasa oficial está vencida; carga una tasa oficial manual para continuar.»; a payment naming a draft or cancelled document reads «El documento no admite pagos en estado ».", "type": "string" }, "error_code": { "description": "The code to branch on, open-ended: the item's own domain error code (e.g. invalid_payment_status_transition, payment_payable_not_payable, payment_line_derives_no_debt for a line whose units derive no cent of debt at the official rate of the application date, payment_method_instrument_treasury_account_inactive with reason treasury_account_missing when a method line's position has no treasury account, payment_persistence_failed), payment_not_found, accounting_configuration_incomplete for a blocked official rate, or payment_apply_failed for any other failure.", "type": "string", "example": "invalid_payment_status_transition" } }, "type": "object" } } }, "type": "object" } } } }, "403": { "description": "Unauthorized" }, "422": { "description": "Validation refuses the body: `errors` names `ids` (missing or empty), `ids.N` (not a UUID) or `date_payment_applied` (missing or not a date), and `error_code` is null. Or `date_payment_applied` is after the company today (error_code cash_event_date_in_the_future): the batch is refused before any payment is read, and no item is applied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/payments/bulk-approve": { "post": { "tags": [ "Backoffice - Purchases Payments" ], "summary": "Bulk approve payments", "description": "A payment already approved counts in success_count with nothing written; an applied or cancelled payment fails with invalid_payment_status_transition.", "operationId": "895fac13e0a5aa22c8f47bf54e59c954", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "ids": { "description": "Array of payment IDs to approve", "type": "array", "items": { "type": "string" } } }, "type": "object" } } } }, "responses": { "200": { "description": "Bulk approval completed", "content": { "application/json": { "schema": { "properties": { "success_count": { "type": "integer" }, "failed_count": { "type": "integer" }, "failures": { "type": "array", "items": { "required": [ "payment_id", "payment_code", "error", "error_code" ], "properties": { "payment_id": { "type": "string" }, "payment_code": { "type": "string" }, "error": { "description": "Why this item was not approved; nothing of it was written.", "type": "string" }, "error_code": { "description": "The code to branch on, open-ended: the item's own domain error code (e.g. invalid_payment_status_transition, payment_method_snapshot_missing, payment_persistence_failed, or purchases_provider_inactive for a supplier advance whose provider was deactivated, MER-5279), payment_not_found, or payment_approve_failed for any other failure.", "type": "string", "example": "payment_approve_failed" } }, "type": "object" } } }, "type": "object" } } } }, "403": { "description": "Unauthorized" }, "422": { "description": "Validation refuses `ids`: `errors` names `ids` (missing or empty) or `ids.N` (not a UUID), and `error_code` is null.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/payments/bulk-cancel": { "post": { "tags": [ "Backoffice - Purchases Payments" ], "summary": "Bulk cancel payments", "operationId": "7ac938ae5fc8fddc09875e9eac14b508", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "ids": { "description": "Array of payment IDs to cancel", "type": "array", "items": { "type": "string" } } }, "type": "object" } } } }, "responses": { "200": { "description": "Bulk cancel completed", "content": { "application/json": { "schema": { "properties": { "success_count": { "type": "integer" }, "failed_count": { "type": "integer" }, "failures": { "type": "array", "items": { "required": [ "payment_id", "payment_code", "error", "error_code" ], "properties": { "payment_id": { "type": "string" }, "payment_code": { "type": "string" }, "error": { "description": "Why this item was not cancelled; nothing of it was written.", "type": "string" }, "error_code": { "description": "The code to branch on, open-ended: the item's own domain error code (e.g. advance_has_applications, company_not_found, payment_persistence_failed), payment_not_found, or payment_cancel_failed for any other failure.", "type": "string", "example": "payment_cancel_failed" } }, "type": "object" } } }, "type": "object" } } } }, "403": { "description": "Unauthorized" }, "422": { "description": "Validation refuses `ids`: `errors` names `ids` (missing or empty) or `ids.N` (not a UUID), and `error_code` is null.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/payments/{id}/cancel": { "post": { "tags": [ "Backoffice - Purchases Payments" ], "summary": "Cancel a payment", "description": "Repeats answer 200 null without writes. An applied advance without live applications restores its frozen treasury keys, zeros its own balances, retains method payout facts and reverses the exact original posting as purchase_payment.advance_cancelled, dated company today and linked by reverses_transaction_id; no fresh rate is requested. A draft posts nothing.", "operationId": "ad644eeb698e45df05a2ebd234400585", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Payment cancelled successfully" }, "400": { "description": "invalid_payment_status_transition: the payment cannot move to cancelled; the detail names both statuses. Cancelling a cancelled payment is a repeat and answers 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentProblem" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentProblem" } } } }, "404": { "description": "Payment not found", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PaymentProblem" }, { "$ref": "#/components/schemas/PaymentMiddlewareError" } ] } } } }, "500": { "description": "payment_persistence_failed, payment_advance_integrity_error, or purchase_payment_advance_posted_transaction_missing (an applied advance has no original posting); the transaction rolls back.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentProblem" } } } }, "409": { "description": "advance_has_applications: an advance with live applications cannot be cancelled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentProblem" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentMiddlewareError" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/payment-documents/{id}": { "get": { "tags": [ "Backoffice - Purchases Payments" ], "summary": "A debt as Payments reads it, including settled documents", "operationId": "5252f612efaaf98c4d1a62585ba6fb07", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Debt identity and settlement facts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentDocument" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Payments view permission required" }, "404": { "description": "Debt not found in this company" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/payment-documents": { "get": { "tags": [ "Backoffice - Purchases Payments" ], "summary": "Open provider debts for the Payments form", "operationId": "f6ce5f5b0e37af7f2fd257c38864658f", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "provider_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "kinds[]", "in": "query", "schema": { "type": "array", "items": { "type": "string", "enum": [ "regular", "opening", "debit_note" ] } } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "Only debt identity and settlement facts", "content": { "application/json": { "schema": { "required": [ "items", "total", "per_page", "current_page" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentDocument" } }, "total": { "type": "integer" }, "per_page": { "type": "integer" }, "current_page": { "type": "integer" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Payments view permission required" }, "422": { "description": "Invalid query" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/credit-applications/open-documents": { "get": { "tags": [ "Backoffice - Purchases Payments" ], "summary": "Open provider documents for the credit application action", "operationId": "d4c65711685c554e11fdfbe76ab8ad05", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "provider_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "kinds[]", "in": "query", "schema": { "type": "array", "items": { "type": "string", "enum": [ "regular", "opening", "debit_note" ] } } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "Paginated payable document facts", "content": { "application/json": { "schema": { "required": [ "items", "total", "per_page", "current_page" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentDocument" } }, "total": { "type": "integer" }, "per_page": { "type": "integer" }, "current_page": { "type": "integer" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Credit application permission required" }, "422": { "description": "Invalid query" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/payments/{id}": { "get": { "tags": [ "Backoffice - Purchases Payments" ], "summary": "Get a payment by ID", "operationId": "d8e0f09e5c4864be9013b357952760da", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Payment details", "content": { "application/json": { "schema": { "properties": { "created_at": { "description": "Persisted record creation timestamp in UTC; null only when unavailable.", "type": "string", "format": "date-time", "nullable": true }, "updated_at": { "description": "Persisted record update timestamp in UTC; null only when unavailable.", "type": "string", "format": "date-time", "nullable": true }, "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "starter": { "type": "object" }, "date_payment": { "type": "string", "format": "date" }, "provider_id": { "type": "string", "format": "uuid" }, "provider_name": { "description": "Stored provider name from the document company; null when unavailable.", "type": "string", "nullable": true }, "kind": { "type": "string", "enum": [ "settlement", "advance" ] }, "currency": { "type": "string", "nullable": true }, "balance": { "type": "string", "example": "500.00", "nullable": true }, "functional_balance": { "type": "string", "nullable": true }, "reporting_balance": { "type": "string", "nullable": true }, "amount_paid": { "type": "string", "example": "1000.00" }, "date_payment_applied": { "type": "string", "format": "date", "nullable": true }, "status": { "type": "string" }, "payables": { "description": "The allocation lines, each with what it settled once the payment was applied (MER-3120).", "type": "array", "items": { "$ref": "#/components/schemas/PaymentPayableLine" } }, "methods": { "description": "The method lines in form order, each with its payment instrument, the Method Line Snapshot it posts to (ADR 0183) and, once applied, its settlement (MER-3120).", "type": "array", "items": { "$ref": "#/components/schemas/PaymentMethodLine" } }, "responsible_user_id": { "type": "string", "nullable": true } }, "type": "object" } } } }, "404": { "description": "Payment not found", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PaymentProblem" }, { "$ref": "#/components/schemas/PaymentMiddlewareError" } ] } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentProblem" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentMiddlewareError" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Backoffice - Purchases Payments" ], "summary": "Update a payment", "description": "An advance (kind=advance) starts from provider with starter.id=provider_id, has no payables, and counts positive method units in one instrument currency; their settling units (amountPaid − igtf_paid_amount) total amount_paid. USDT and agreed rates reject. Clients cannot submit currency or own balances. Approval freezes all advance financial terms including references. While the payment awaits approval everything is replaced and each method line takes its snapshot again; from approval on its financial terms are frozen. Each method line counts its amountPaid in its instrument's currency, which may be any. The invoices of a payment share one currency and the payables add up to amount_paid in it; the lines' settling units (amountPaid − igtf_paid_amount) add up to it too when they are all in that currency. A line in another currency converts at the official rate when the payment is applied, which only USD and VES have, so the payment settles a single invoice and its payable amountPaid is the debt its approver expects. A line may instead settle at an agreed settlement rate (methods[].agreed_rate, MER-3125): while the payment awaits approval an omitted rate takes the provider's current terms, the rate stored is kept when sent again, and any other rate is captured by the editor under backoffice.purchases.payments.agree-settlement-rate and audited; from approval on the rate is frozen with the rest of the line.", "operationId": "df5dc9e393f6dafe3f9b13218319e0c0", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "starter", "date_payment", "provider_id", "amount_paid", "methods" ], "properties": { "kind": { "description": "Missing on create defaults to settlement; missing on update preserves stored kind. Kind is immutable after create.", "type": "string", "enum": [ "settlement", "advance" ] }, "starter": { "required": [ "id", "type" ], "properties": { "id": { "description": "For an advance, this is provider_id and must belong to the company. For a settlement, the document of the company the payment was started from: a purchases invoice (regular or opening) or a supplier debit note (MER-3291), still named as an `invoice`. A missing or foreign document, or a supplier credit note (ADR 0216), answers 422 with `errors` naming this field.", "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174001" }, "type": { "type": "string", "example": "invoice", "enum": [ "invoice", "provider" ] } }, "type": "object" }, "date_payment": { "description": "Validated as a date; the API stores and returns Y-m-d.", "type": "string", "format": "date", "example": "2026-09-27" }, "provider_id": { "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174002" }, "amount_paid": { "description": "Number or decimal string, zero or more, with at most two decimals.", "oneOf": [ { "type": "number", "example": 100, "minimum": 0 }, { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,2})?$", "example": "100.00" } ] }, "payables": { "description": "Settlement requires at least one invoice; advance may omit this field or send an empty array.", "type": "array", "items": { "$ref": "#/components/schemas/PaymentPayableRequestLine" } }, "methods": { "description": "The method lines, in form order. While the payment awaits approval their snapshot is taken again; once approved they must name the same instruments for the same amounts and IGTF Paid (422 payment_financial_fields_cannot_be_modified, detail names `methods`).", "type": "array", "items": { "$ref": "#/components/schemas/PaymentMethodRequestLine" }, "minItems": 1 } }, "type": "object" } } } }, "responses": { "200": { "description": "Payment updated successfully" }, "400": { "description": "payment_cannot_be_modified (an applied or cancelled payment), invoice_already_fully_paid (the invoice has nothing left open) or payment_exceeds_invoice_balance (a payable applies more than the invoice still owes): for the two invoice refusals the detail names the invoice's currency, and the body adds `invoice_code`, `invoice_total`, `payment_amount`, `currency` and, for the latter, `available_balance` (see PaymentInvoiceBalanceProblem)", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/PaymentProblem" }, { "$ref": "#/components/schemas/PaymentInvoiceBalanceProblem" } ] } } } }, "403": { "description": "Without the route's permission; or payment_agreed_settlement_rate_not_permitted: a method line's agreed_rate departs from the settlement terms of the provider its invoices belong to, or is captured with no terms to follow, without backoffice.purchases.payments.agree-settlement-rate; `errors` names that line's `methods.N.agreed_rate` (N counts from 0)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentProblem" } } } }, "404": { "description": "Payment not found, or payment_method_instrument_not_found: the payment instrument does not exist or belongs to another company (same body for both).", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PaymentProblem" }, { "$ref": "#/components/schemas/PaymentMiddlewareError" } ] } } } }, "422": { "description": "payment_financial_fields_cannot_be_modified: the payment is to be applied and the edit changes a frozen financial term; the detail names it (date_payment, amount_paid, payables, methods, starter or provider_id) and nothing is written. Advance refusals: advance_single_currency, advance_usdt_not_supported, advance_agreed_rate_not_supported, advance_provider_not_found, advance_starter_provider_mismatch, and purchases_provider_inactive with `errors.provider_id` when an advance awaiting approval keeps or names an inactive provider (MER-5279; a settlement never checks it); update kind changes: payment_kind_immutable; payment_settlement_requires_invoice rejects an advance-shaped edit of a stored settlement. The body is invalid (`errors` names each field, `methods.N.reference` when a line's reference is a JSON list or has a whole-number key); or `error_code` is payment_method_instrument_inactive or payment_method_instrument_treasury_account_inactive (Problem `reason` may be inactive or treasury_account_missing), for the first failing method line in form order (only while the payment awaits approval); or `error_code` payment_agreed_settlement_rate_required, payment_agreed_settlement_rate_converts_nothing or payment_currency_pair_not_supported with `errors` naming `methods.N.agreed_rate` when the refusal is about a line's agreed rate; or `error_code` payment_igtf_paid_exceeds_cash with `errors` naming `methods.N.igtf_paid_amount` (a line's IGTF Paid is not lower than its cash); or `error_code` payment_line_derives_no_debt with `errors` naming `methods.N.amountPaid` (a line's settling units derive less than one cent of the invoices' currency at its agreed rate; the body adds `method_line`, `units`, `units_currency`, `currency` and `rate_basis`, see PaymentLineDerivesNoDebtProblem); or derived_debt_does_not_match_applied_amounts (the debt the agreed rates derive is not what the payables apply; the body adds `derived`, `applied` and `currency`, with `open` null, see PaymentSettlementRejectionProblem); or `error_code` payment_amount_inconsistency (the payables and amount_paid differ, or method lines in the currency of the invoices do not add up to them); or payment_settles_an_invoice_twice (two payables name the same invoice); or payment_mixes_document_currencies (the invoices are in several currencies); or payment_official_conversion_settles_one_invoice (a line in another currency than the invoices converts at the official rate, which settles a single invoice); or payment_agreed_settlement_rate_required (a USDT line against invoices in another currency); or payment_currency_pair_not_supported (a line in another currency than the invoices converts at the official rate only between USD and VES; the detail names both currencies); or purchases_invoice_not_found (an invoice removed while the payment was being written); or payment_payable_not_payable (a payable names an invoice, opening or debit note that is a draft or cancelled; the detail names its code and status; nothing is written); or payment_payable_provider_mismatch (a payable names a document of another provider; the detail names only that document's id; nothing is written).", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/PaymentProblem" }, { "$ref": "#/components/schemas/PaymentLineDerivesNoDebtProblem" }, { "$ref": "#/components/schemas/PaymentSettlementRejectionProblem" } ] } } } }, "409": { "description": "payment_payable_id_conflict: a payables[].id is already used by another payment line, or repeated in this request; nothing is written; the detail names only the id sent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentProblem" } } } }, "500": { "description": "The payment could not be persisted (error_code: payment_persistence_failed)" }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentMiddlewareError" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/payments": { "get": { "tags": [ "Backoffice - Purchases Payments" ], "summary": "Search payments", "operationId": "aaf17429ee30915ffe2505b9e1379855", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "to_be_approved", "to_be_applied", "applied", "cancelled" ] } }, { "name": "kind", "in": "query", "description": "One kind. To match several, send kind[] (MER-3640).", "schema": { "type": "string", "enum": [ "settlement", "advance" ] } }, { "name": "kind[]", "in": "query", "description": "Nonempty list; OR within the field, AND with other filters (MER-3640).", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "settlement", "advance" ] }, "minItems": 1 } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 20 } }, { "name": "invoice_id", "in": "query", "description": "Filter payments by invoice ID", "schema": { "type": "string" } }, { "name": "instrument_id", "in": "query", "description": "Only payments with at least one method line through this payment instrument", "schema": { "type": "string", "format": "uuid" } }, { "name": "sort_by", "in": "query", "description": "Any column of backoffice__purchases__payments, bare or prefixed with the table name and a dot. Without it the list orders by code descending. An empty value counts as absent. Any other value answers 422 invalid_list_sort.", "required": false, "schema": { "type": "string" } }, { "name": "sort_order", "in": "query", "description": "Checked even without sort_by, but it only orders a sort_by that is sent; a sort_by without it reads descending. Read ignoring case and surrounding spaces. An empty value counts as absent. Any other value answers 422 invalid_list_sort.", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "List of payments", "content": { "application/json": { "schema": { "properties": { "items": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "date_payment": { "type": "string", "format": "date" }, "provider_id": { "type": "string", "format": "uuid" }, "provider_name": { "type": "string", "nullable": true }, "kind": { "type": "string", "enum": [ "settlement", "advance" ] }, "currency": { "type": "string", "nullable": true }, "balance": { "type": "string", "example": "500.00", "nullable": true }, "functional_balance": { "type": "string", "nullable": true }, "reporting_balance": { "type": "string", "nullable": true }, "amount_paid": { "type": "string", "example": "100.00" }, "date_payment_applied": { "type": "string", "format": "date", "nullable": true }, "status": { "type": "string" }, "methods": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentMethodSnapshotLine" } }, "hasAccountingConfigurationGaps": { "type": "boolean" } }, "type": "object" } }, "total": { "type": "integer" }, "per_page": { "type": "integer" }, "current_page": { "type": "integer" } }, "type": "object" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentProblem" } } } }, "422": { "description": "Query validation of kind (error_code null, errors.kind or errors.kind.N: an unknown kind, or a kind list that is empty or nested) or invalid_list_sort (errors.sort_by or errors.sort_order).", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/PaymentProblem" }, { "$ref": "#/components/schemas/InvalidListSortProblem" } ] } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentMiddlewareError" } } } }, "404": { "description": "Unknown or inaccessible tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentMiddlewareError" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Purchases Payments" ], "summary": "Create a new payment", "description": "An advance (kind=advance) starts from provider with starter.id=provider_id, has no payables, and counts positive method units in one instrument currency; their settling units (amountPaid − igtf_paid_amount) total amount_paid. USDT and agreed rates reject. Clients cannot submit currency or own balances. Approval freezes all advance financial terms including references. A payment is created to be approved. Each method line goes through an active payment instrument of the company, in any currency (pick one from GET /treasury/payment-instruments/lookup), counts its amountPaid in the instrument's currency and takes the treasury account and accounting account it posts to; that snapshot is taken again on every edit and fixed from approval. The invoices of a payment share one currency. The payables add up to amount_paid, in the currency of the invoices; the lines' settling units (amountPaid − igtf_paid_amount) add up to it too when they are all in that currency. A line in another currency converts at the official rate when the payment is applied, which only USD and VES have, so such a payment settles a single invoice and its payable amountPaid is the debt its approver expects (the debt actually settled is derived when the payment is applied). A line may instead settle at an agreed settlement rate (methods[].agreed_rate, MER-3125): a USDT line takes the settlement terms of the provider its invoices belong to, or a rate captured under backoffice.purchases.payments.agree-settlement-rate, audited as backoffice.purchases.payment.agreed_settlement_rate_overridden.v1; its debt is then known, the payables must apply exactly the debt the lines derive, and the payment may settle several invoices. Idempotent on `id`: resending an id already stored with the same content answers 200 with the payment as it stands now (it may be applied or cancelled since), writes nothing and records no event; its invoices and instruments are not checked again. The content is the same when kind, starter, date_payment (its day), provider_id, amount_paid (to the cent), the payables and the methods match; UUIDs compare case-insensitively. Payables compare at each position by id, payableId, type and amountPaid, and methods at each position by instrument_id, amountPaid, igtf_paid_amount and reference, whose keys may come in any order but whose values compare strictly; so the lines must come in the same order and number. responsible_user_id is not compared. The comparison is against the payment as it stands, so a resend after an edit (PUT) answers 409. Any other content under a stored id, or the id of a payment of another company, answers 409 payment_id_conflict and leaves the stored payment as it was.", "operationId": "1e666abc6a633b687e8ec125649182d6", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "id", "starter", "date_payment", "provider_id", "amount_paid", "methods" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000" }, "kind": { "description": "Missing on create defaults to settlement; missing on update preserves stored kind. Kind is immutable after create.", "type": "string", "enum": [ "settlement", "advance" ] }, "starter": { "required": [ "id", "type" ], "properties": { "id": { "description": "For an advance, this is provider_id and must belong to the company. For a settlement, the document of the company the payment was started from: a purchases invoice (regular or opening) or a supplier debit note (MER-3291), still named as an `invoice`. A missing or foreign document, or a supplier credit note (ADR 0216), answers 422 with `errors` naming this field.", "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174001" }, "type": { "type": "string", "example": "invoice", "enum": [ "invoice", "provider" ] } }, "type": "object" }, "date_payment": { "description": "Validated as a date; the API stores and returns Y-m-d.", "type": "string", "format": "date", "example": "2026-09-27" }, "provider_id": { "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174002" }, "amount_paid": { "description": "Number or decimal string, zero or more, with at most two decimals.", "oneOf": [ { "type": "number", "example": 100, "minimum": 0 }, { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,2})?$", "example": "100.00" } ] }, "payables": { "description": "Settlement requires at least one invoice; advance may omit this field or send an empty array.", "type": "array", "items": { "$ref": "#/components/schemas/PaymentPayableRequestLine" } }, "methods": { "description": "The method lines, in form order; the entry spreads them over the payables in cascade.", "type": "array", "items": { "$ref": "#/components/schemas/PaymentMethodRequestLine" }, "minItems": 1 }, "responsible_user_id": { "description": "Optional company user id for the Payment Responsable", "type": "string", "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Payment created, to be approved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentCreateResult" } } } }, "200": { "description": "The id was already stored with the same content: nothing was written and the payment is answered as it stands now", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentCreateResult" } } } }, "400": { "description": "invoice_already_fully_paid (the invoice has nothing left open) or payment_exceeds_invoice_balance (a payable applies more than the invoice still owes): the detail names the invoice's currency, and the body adds `invoice_code`, `invoice_total`, `payment_amount`, `currency` and, for the latter, `available_balance` (see PaymentInvoiceBalanceProblem)", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/PaymentProblem" }, { "$ref": "#/components/schemas/PaymentInvoiceBalanceProblem" } ] } } } }, "403": { "description": "Advance requires backoffice.purchases.payments.advance; omitted kind or settlement requires backoffice.purchases.payments.create. Entry accepts either permission, then checks the exact kind before creating. Without that permission; or payment_agreed_settlement_rate_not_permitted: a method line's agreed_rate departs from the settlement terms of the provider its invoices belong to, or is captured with no terms to follow, without backoffice.purchases.payments.agree-settlement-rate; `errors` names that line's `methods.N.agreed_rate` (N counts from 0)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentProblem" } } } }, "404": { "description": "payment_method_instrument_not_found: the payment instrument does not exist or belongs to another company (same body for both).", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PaymentProblem" }, { "$ref": "#/components/schemas/PaymentMiddlewareError" } ] } } } }, "409": { "description": "payment_id_conflict: the id is already used by a payment with other content, or by a payment of another company; or payment_payable_id_conflict: a payables[].id is already used by another payment line. The detail names only the identifier sent.", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "detail": { "type": "string", "example": "El identificador <123e4567-e89b-12d3-a456-426614174000> ya lo usa otro pago" }, "error_code": { "type": "string", "example": "payment_id_conflict", "enum": [ "payment_id_conflict", "payment_payable_id_conflict" ] } }, "type": "object" } } } }, "422": { "description": "Advance refusals: advance_single_currency, advance_usdt_not_supported, advance_agreed_rate_not_supported, advance_provider_not_found, advance_starter_provider_mismatch, and purchases_provider_inactive with `errors.provider_id` when the advance names an inactive provider (MER-5279; a resend of an advance already created answers it as stored, and a settlement never checks it). The body is invalid (`errors` names each field, `methods.N.reference` when a line's reference is a JSON list or has a whole-number key); or `error_code` is payment_method_instrument_inactive or payment_method_instrument_treasury_account_inactive (Problem `reason` may be inactive or treasury_account_missing), for the first failing method line in form order; or `error_code` payment_agreed_settlement_rate_required, payment_agreed_settlement_rate_converts_nothing or payment_currency_pair_not_supported with `errors` naming `methods.N.agreed_rate` when the refusal is about a line's agreed rate; or `error_code` payment_igtf_paid_exceeds_cash with `errors` naming `methods.N.igtf_paid_amount` (a line's IGTF Paid is not lower than its cash); or `error_code` payment_line_derives_no_debt with `errors` naming `methods.N.amountPaid` (a line's settling units derive less than one cent of the invoices' currency at its agreed rate; the body adds `method_line`, `units`, `units_currency`, `currency` and `rate_basis`, see PaymentLineDerivesNoDebtProblem); or derived_debt_does_not_match_applied_amounts (the debt the agreed rates derive is not what the payables apply; the body adds `derived`, `applied` and `currency`, with `open` null, see PaymentSettlementRejectionProblem); or `error_code` payment_amount_inconsistency (the payables and amount_paid differ, or method lines in the currency of the invoices do not add up to them); or payment_settles_an_invoice_twice (two payables name the same invoice); or payment_mixes_document_currencies (the invoices are in several currencies); or payment_official_conversion_settles_one_invoice (a line in another currency than the invoices converts at the official rate, which settles a single invoice); or payment_agreed_settlement_rate_required (a USDT line against invoices in another currency); or payment_currency_pair_not_supported (a line in another currency than the invoices converts at the official rate only between USD and VES; the detail names both currencies); or purchases_invoice_not_found (an invoice removed while the payment was being written); or payment_payable_not_payable (a payable names an invoice, opening or debit note that is a draft or cancelled; the detail names its code and status; nothing is written); or payment_payable_provider_mismatch (a payable names a document of another provider; the detail names only that document's id; nothing is written).", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/PaymentProblem" }, { "$ref": "#/components/schemas/PaymentLineDerivesNoDebtProblem" }, { "$ref": "#/components/schemas/PaymentSettlementRejectionProblem" } ] } } } }, "500": { "description": "The payment could not be persisted (error_code: payment_persistence_failed)" }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentMiddlewareError" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/payments/{id}/responsible": { "put": { "tags": [ "Backoffice - Purchases Payments" ], "summary": "Reassign the responsible user of a payment", "operationId": "905ca164071a39bf180f817a28da691f", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "responsible_user_id" ], "properties": { "responsible_user_id": { "description": "Company user id that becomes the Payment Responsable; null clears it", "type": "string", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Responsible reassigned" }, "403": { "description": "Forbidden" }, "404": { "description": "Payment not found" }, "409": { "description": "Responsible cannot be reassigned in the current status" }, "422": { "description": "Validation error" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/payments/export-binance-pay": { "get": { "tags": [ "Backoffice - Purchases Payments" ], "summary": "Export payments to Binance Pay", "description": "An xlsx of Binance Pay transfers (Email, Amount, Currency, Description «Pago {code}») for every payment matching the list filters, across all result pages. A method line is exported when its payment instrument is a crypto wallet, the line is in USDT and its `reference.email` is set; the Currency column writes the line's currency. A line in another currency (a `MIG-BINANCE-…` instrument kept in the functional currency, ADR 0204) or still awaiting its snapshot is left out. Without `status`, or with `all`, the export covers payments to be applied. No matching line answers 404 with the problem `binance_pay_export_has_no_lines`; its `detail` is the sentence the Backoffice shows.", "operationId": "425b0c6d496011a0fb9db8cb27fc946d", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "to_be_approved", "to_be_applied", "applied", "cancelled" ] } }, { "name": "kind", "in": "query", "description": "One kind, as on the payments list. To match several, send kind[] (MER-3640).", "schema": { "type": "string", "enum": [ "settlement", "advance" ] } }, { "name": "kind[]", "in": "query", "description": "Nonempty list; OR within the field, AND with other filters (MER-3640).", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "settlement", "advance" ] }, "minItems": 1 } } ], "responses": { "200": { "description": "Exported payments", "headers": { "Cache-Control": { "description": "Always no-store: the workbook is never cached", "schema": { "type": "string", "example": "no-store, private" } } }, "content": { "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": {} } }, "403": { "description": "Unauthorized" }, "404": { "description": "binance_pay_export_has_no_lines: no payment method line to export. An unknown company in the path is answered by the tenant middleware with a message instead.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PaymentProblem" }, { "$ref": "#/components/schemas/PaymentMiddlewareError" } ] } } } }, "422": { "description": "An unknown kind, or a kind list that is empty or nested (MER-3640).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/providers/lookup": { "get": { "tags": [ "Backoffice - Purchases - Provider Lookups" ], "summary": "Lookup Providers for tenant forms", "operationId": "18cba8056075afd232791bedefc44a8a", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "active", "inactive" ] } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 200, "minimum": 1 } } ], "responses": { "200": { "description": "Minimal Provider projection", "content": { "application/json": { "schema": { "properties": { "items": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "vat_taxpayer_type": { "description": "Fiscal VAT classification for purchase-line proposals.", "type": "string", "nullable": true }, "default_payment_term": { "type": "string", "nullable": true, "enum": [ "cash", "five_days", "seven_days", "fifteen_days", "thirty_days" ] }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "fiscal_identity": { "properties": { "document_type": { "type": "string", "nullable": true }, "document_number": { "type": "string", "nullable": true }, "legal_name": { "type": "string", "nullable": true }, "complete": { "type": "boolean" }, "missing": { "type": "array", "items": { "type": "string" } } }, "type": "object" } }, "type": "object" } }, "total": { "type": "integer" }, "per_page": { "type": "integer" }, "current_page": { "type": "integer" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Not a member of this tenant" }, "404": { "description": "company_not_found: the company does not exist. An unknown tenant is answered by the middleware with message.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProviderMiddlewareError" }, { "$ref": "#/components/schemas/ProviderProblem" } ] } } } }, "422": { "description": "Invalid status filter" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/providers/{id}/activation": { "put": { "tags": [ "Backoffice - Purchases - Providers" ], "summary": "Provider activation", "description": "Requires `backoffice.purchases.providers.update`. Repeated requests are a no-op.", "operationId": "2ff634be23a0bd9ea254995738f87aa6", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "State saved" }, "403": { "description": "Missing update permission" }, "404": { "description": "Provider not found" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/providers/{id}/credit-balances": { "get": { "tags": [ "Backoffice - Purchases - Providers" ], "summary": "Read what a provider's supplier advances and Supplier Credit still hold", "description": "The provider's paid-out supplier advances that still hold a balance, grouped by currency and never summed across currencies (MER-3276), so a payment form can warn before paying again what an advance already covers. Each currency group carries reporting_balance, its equivalent in the top-level reporting_currency (MER-3281): the stored reporting-book Carrying Amount summed within that currency, a book value, never a conversion at today's rate. Beside them, under supplier_credit_balances, the provider's credit notes that keep Supplier Credit, grouped by currency and never summed with the advances, each with its reporting_balance (MER-3281); the notes are listed only for a caller with backoffice.purchases.credit-notes.view, the amounts always are. Supplier Credit is shown for information: it cannot be applied to other invoices yet. Requires backoffice.purchases.payments.view.", "operationId": "getProviderCreditBalances", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The provider's open advances and Supplier Credit by currency; each list is empty when there is none", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderCreditBalances" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentMiddlewareError" } } } }, "403": { "description": "The user lacks backoffice.purchases.payments.view" }, "404": { "description": "provider_not_found: the provider does not exist or belongs to another company (same body for either); company_not_found: the company does not exist. An unknown tenant, or an id that is not a UUID, is answered with message.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PaymentMiddlewareError" }, { "$ref": "#/components/schemas/SupplierCreditApplicationProblem" } ] } } } }, "503": { "description": "provider_supplier_credits_query_failed: the advances or the Supplier Credit could not be read now; retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupplierCreditApplicationProblem" } } } }, "500": { "description": "provider_supplier_credits_invalid_data: a stored advance or credit note has a currency, date or balance that cannot be interpreted; reported", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupplierCreditApplicationProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/providers/{id}/deactivation": { "put": { "tags": [ "Backoffice - Purchases - Providers" ], "summary": "Provider deactivation", "description": "Requires `backoffice.purchases.providers.update`. Repeated requests are a no-op.", "operationId": "f9a3877819b8d8040d1be08b54021ddb", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "State saved" }, "403": { "description": "Missing update permission" }, "404": { "description": "Provider not found" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/providers/email-warning/lookup": { "get": { "tags": [ "Backoffice - Purchases - Providers" ], "summary": "Whether current company tax attributes designate a VAT or ISLR withholding agent", "description": "Membership-only projection for supplier contact warnings. Null means tax attributes are not configured on today in the company timezone. Does not require fiscal-settings permissions.", "operationId": "getProviderEmailWarning", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Current designation only", "content": { "application/json": { "schema": { "required": [ "withholding_agent" ], "properties": { "withholding_agent": { "type": "boolean", "nullable": true } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Tenant membership denied" }, "404": { "description": "Company not found" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/providers/import": { "post": { "tags": [ "Backoffice - Providers" ], "summary": "Import providers from Excel file", "description": "Imports providers from an Excel file", "operationId": "10db330d477aa38bc730ce3020cb046d", "parameters": [ { "name": "tenant", "in": "path", "description": "Company tenant ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "properties": { "file": { "description": "Excel file with providers", "type": "string", "format": "binary" } }, "type": "object" } } } }, "responses": { "202": { "description": "Import started successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean" }, "import_id": { "type": "string", "format": "uuid" }, "message": { "type": "string" } }, "type": "object" } } } }, "403": { "description": "Unauthorized - User does not have permission to import providers" }, "422": { "description": "Validation error - Invalid file format or missing file" }, "500": { "description": "Internal server error" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/providers/import/{importId}/status": { "get": { "tags": [ "Backoffice - Providers" ], "summary": "Get import status", "description": "Returns the current status of a provider import job", "operationId": "e8e15ceb31e5dde20c686baca6c72bdf", "parameters": [ { "name": "tenant", "in": "path", "description": "Company tenant ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "importId", "in": "path", "description": "Import job ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Import status retrieved successfully", "content": { "application/json": { "schema": { "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed" ] }, "progress": { "type": "integer" }, "imported_count": { "type": "integer" }, "total_count": { "type": "integer" }, "errors": { "type": "array", "items": { "type": "string" } }, "original_filename": { "type": "string" }, "started_at": { "type": "string", "format": "date-time", "nullable": true }, "completed_at": { "type": "string", "format": "date-time", "nullable": true } }, "type": "object" } } } }, "404": { "description": "Import job not found" }, "403": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/providers/{id}/settlement-terms": { "get": { "tags": [ "Backoffice - Purchases - Providers" ], "summary": "Read a provider's settlement terms", "description": "The Agreed Settlement Rates the provider declared, one per pair of currencies, with who declared each and when. A USDT payment line paying the provider's invoices copies the term of its pair unless it captures another rate. Readable with providers.view, or with payments.create / payments.update so the payments form can prefill a USDT line's agreed rate and derive its payables (MER-3126).", "operationId": "ce65175feae8df8e81377c5fc4990856", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The provider's terms, empty when it has none", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderSettlementTermsView" } } } }, "403": { "description": "Without backoffice.purchases.providers.view, backoffice.purchases.payments.create or backoffice.purchases.payments.update" }, "404": { "description": "provider_not_found: the provider does not exist or belongs to another company (same body for both)" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Backoffice - Purchases - Providers" ], "summary": "Declare a provider's settlement terms", "description": "DeclareProviderSettlementTerms (ADR 0201): replaces the provider's whole set of Agreed Settlement Rates; an empty list withdraws them all. Only USDT settling USD or VES has terms. A term sent again at the same rate keeps its declarer and instant; any change is audited as backoffice.purchases.provider.settlement_terms_changed.v1 with the set after and before, and a declaration that changes nothing writes and audits nothing. The declarer is the user, or the owner of the API key the request authenticates with. Changing the terms never changes a payment already applied.", "operationId": "ebbe3cd137c9cca5087cf7859e0cb717", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "terms" ], "properties": { "terms": { "description": "The whole set, one per pair.", "type": "array", "items": { "$ref": "#/components/schemas/ProviderSettlementTermRequestLine" }, "maxItems": 10 } }, "type": "object" } } } }, "responses": { "200": { "description": "The provider's terms as they now stand", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderSettlementTermsView" } } } }, "403": { "description": "Without backoffice.purchases.payments.agree-settlement-rate" }, "404": { "description": "provider_not_found: the provider does not exist or belongs to another company (same body for both)" }, "422": { "description": "The body is invalid (`errors` names each field); or `error_code` is invalid_currency, provider_settlement_terms_pair_not_supported (only USDT settling USD or VES) or provider_settlement_terms_pair_repeated, with `errors` naming the field of the term at fault (`terms.N.payment_currency` or `terms.N.settled_currency`).", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string" }, "error_code": { "type": "string", "example": "provider_settlement_terms_pair_repeated", "nullable": true }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/providers/template-import": { "get": { "tags": [ "Backoffice - Providers" ], "summary": "Download providers import template", "description": "Downloads an Excel template file for importing providers", "operationId": "e08e5cca87c5f37d98a6a22ea503d38f", "parameters": [ { "name": "tenant", "in": "path", "description": "Company tenant ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Excel template file downloaded successfully", "headers": { "Cache-Control": { "description": "Always no-store: the workbook is never cached", "schema": { "type": "string", "example": "no-store, private" } } }, "content": { "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": {} } }, "403": { "description": "Problem JSON, title Forbidden. Without backoffice.purchases.providers.view the route can: middleware answers with error_code and errors null; the tenant middleware stack (API-key guardrails, company access, tenant membership) answers without error_code, with a reason only from tenant membership.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ImportTemplateProblem" }, { "$ref": "#/components/schemas/ImportTemplateMiddlewareForbidden" } ] } } } }, "500": { "description": "Unexpected failure, reported. Problem JSON with error_code and errors null; the detail is generic in production.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportTemplateProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/providers/{id}": { "get": { "tags": [ "Backoffice - Purchases - Providers" ], "summary": "Get a provider by ID", "operationId": "6ef26e299d33557fff87cd52c0e01e63", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Provider details", "content": { "application/json": { "schema": { "properties": { "created_at": { "description": "Persisted record creation timestamp in UTC; null only when unavailable.", "type": "string", "format": "date-time", "nullable": true }, "updated_at": { "description": "Persisted record update timestamp in UTC; null only when unavailable.", "type": "string", "format": "date-time", "nullable": true }, "labels": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "tone": { "type": "string" }, "archived": { "type": "boolean" } }, "type": "object" } }, "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "defaultPaymentTerm": { "type": "string", "nullable": true, "enum": [ "cash", "five_days", "seven_days", "fifteen_days", "thirty_days" ] }, "paymentDestinationClass": { "type": "string", "nullable": true, "enum": [ "cash", "bank_transfer", "mobile_payment", "point_of_sale", "zelle", "crypto_wallet", "check", "card" ] }, "paymentReference": { "properties": { "email": { "type": "string", "format": "email", "nullable": true } }, "type": "object", "nullable": true }, "companyId": { "type": "string", "format": "uuid" }, "fiscalIdentity": { "properties": { "documentType": { "type": "string", "nullable": true }, "documentNumber": { "type": "string", "nullable": true }, "legalName": { "type": "string", "nullable": true }, "fiscalAddress": { "type": "string", "nullable": true }, "phone": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true }, "vatTaxpayerType": { "type": "string", "nullable": true }, "specialTaxpayerSince": { "type": "string", "nullable": true }, "islrPersonType": { "type": "string", "nullable": true }, "complete": { "type": "boolean" }, "missing": { "type": "array", "items": { "type": "string" } } }, "type": "object" } }, "type": "object" } } } }, "403": { "description": "Unauthorized" }, "404": { "description": "provider_not_found: no provider with this id in the company (another company's provider answers the same); company_not_found: the company does not exist. An unknown tenant is answered by the middleware with message.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProviderMiddlewareError" }, { "$ref": "#/components/schemas/ProviderProblem" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Backoffice - Purchases - Providers" ], "summary": "Update an existing provider", "operationId": "3edb7f88c4bfb3ec1f325b098ad1c984", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "status" ], "properties": { "default_payment_term": { "type": "string", "nullable": true, "enum": [ "cash", "five_days", "seven_days", "fifteen_days", "thirty_days" ] }, "name": { "type": "string", "example": "Updated Supplier Name" }, "description": { "type": "string", "example": "Updated description", "nullable": true }, "status": { "type": "string", "example": "active", "enum": [ "active", "inactive" ] }, "payment_destination_class": { "description": "The Payment Instrument class this provider's payment reference serves; a payment through an instrument of another class never takes the reference.", "type": "string", "example": "crypto_wallet", "nullable": true, "enum": [ "cash", "bank_transfer", "mobile_payment", "point_of_sale", "zelle", "crypto_wallet", "check", "card" ] }, "payment_reference": { "properties": { "email": { "type": "string", "format": "email", "example": "updated@binance.com", "nullable": true } }, "type": "object", "nullable": true }, "fiscal_identity": { "properties": { "document_type": { "type": "string", "nullable": true, "enum": [ "rif", "cedula", "passport" ] }, "document_number": { "type": "string", "nullable": true, "maxLength": 32 }, "legal_name": { "type": "string", "nullable": true, "maxLength": 255 }, "fiscal_address": { "type": "string", "nullable": true, "maxLength": 500 }, "phone": { "type": "string", "nullable": true, "maxLength": 32 }, "email": { "type": "string", "format": "email", "nullable": true, "maxLength": 255 }, "vat_taxpayer_type": { "type": "string", "nullable": true, "enum": [ "ordinary", "formal", "non_taxpayer" ] }, "special_taxpayer_since": { "type": "string", "format": "date", "nullable": true }, "islr_person_type": { "type": "string", "nullable": true, "enum": [ "natural_resident", "natural_non_resident", "legal_domiciled", "legal_non_domiciled" ] } }, "type": "object", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Provider updated successfully" }, "403": { "description": "Unauthorized" }, "404": { "description": "Provider not found" }, "409": { "description": "Document already registered", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "detail": { "type": "string" }, "error_code": { "type": "string", "example": "provider_document_already_registered" }, "existing_code": { "type": "string", "example": "PRV00001" } }, "type": "object" } } } }, "422": { "description": "Request or domain validation error", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string" }, "error_code": { "type": "string", "example": "counterparty_fiscal_identity_contradictory", "nullable": true }, "errors": { "description": "Per-field messages; present on request validation failures and null on domain errors.", "type": "object", "nullable": true } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/providers": { "get": { "tags": [ "Backoffice - Purchases - Providers" ], "summary": "Search providers with filters", "operationId": "8645061009308d88f34f340a9446e8db", "parameters": [ { "name": "withoutEmail", "in": "query", "description": "Only suppliers without fiscal contact email", "schema": { "type": "string", "enum": [ "1" ] } }, { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "label_ids[]", "in": "query", "description": "OR label filter; max 20 UUIDs; archived labels do not match.", "schema": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 20 } }, { "name": "name", "in": "query", "schema": { "type": "string" } }, { "name": "code", "in": "query", "schema": { "type": "string" } }, { "name": "description", "in": "query", "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Scalar status filter. `all` and an empty value both mean no status filter; the empty value is accepted but deliberately not published as an enum member. Prefer `status[]` for multi-value filters.", "schema": { "type": "string", "enum": [ "active", "inactive", "all" ] } }, { "name": "status[]", "in": "query", "description": "Repeated status filter values (e.g. status[]=active&status[]=inactive). Empty array means no status filter.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "active", "inactive" ] } } }, { "name": "search", "in": "query", "description": "Free-text search over name, code, description and document_number", "schema": { "type": "string" } }, { "name": "documentNumber", "in": "query", "description": "Exact canonical document number filter", "schema": { "type": "string" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 100, "minimum": 1 } }, { "name": "sort_by", "in": "query", "description": "Absent, the list orders by code descending.", "schema": { "type": "string", "enum": [ "name", "code", "status", "created_at" ] } }, { "name": "sort_order", "in": "query", "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "List of providers", "content": { "application/json": { "schema": { "properties": { "items": { "type": "array", "items": { "properties": { "labels": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "tone": { "type": "string" }, "archived": { "type": "boolean" } }, "type": "object" } }, "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "defaultPaymentTerm": { "type": "string", "nullable": true, "enum": [ "cash", "five_days", "seven_days", "fifteen_days", "thirty_days" ] }, "paymentDestinationClass": { "type": "string", "nullable": true, "enum": [ "cash", "bank_transfer", "mobile_payment", "point_of_sale", "zelle", "crypto_wallet", "check", "card" ] }, "paymentReference": { "properties": { "email": { "type": "string", "format": "email", "nullable": true } }, "type": "object", "nullable": true }, "companyId": { "type": "string", "format": "uuid" }, "fiscalIdentity": { "properties": { "documentType": { "type": "string", "nullable": true }, "documentNumber": { "type": "string", "nullable": true }, "legalName": { "type": "string", "nullable": true }, "fiscalAddress": { "type": "string", "nullable": true }, "phone": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true }, "vatTaxpayerType": { "type": "string", "nullable": true }, "specialTaxpayerSince": { "type": "string", "nullable": true }, "islrPersonType": { "type": "string", "nullable": true }, "complete": { "type": "boolean" }, "missing": { "type": "array", "items": { "type": "string" } } }, "type": "object" } }, "type": "object" } }, "total": { "type": "integer" }, "per_page": { "type": "integer" }, "currentPage": { "type": "integer" }, "meta": { "properties": { "total": { "type": "integer" }, "per_page": { "type": "integer" }, "current_page": { "type": "integer" }, "label_counts": { "description": "Distinct providers per unarchived label; ignores label_ids, retains status and other filters.", "type": "object", "additionalProperties": { "type": "integer" } }, "counts": { "description": "Providers per status under every active filter except status; always carries a key per status.", "properties": { "active": { "type": "integer" }, "inactive": { "type": "integer" } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "403": { "description": "Unauthorized" }, "404": { "description": "company_not_found: the company does not exist. An unknown tenant is answered by the middleware with message.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProviderMiddlewareError" }, { "$ref": "#/components/schemas/ProviderProblem" } ] } } } }, "422": { "description": "Validation error" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Purchases - Providers" ], "summary": "Create a new provider", "operationId": "8ae4f766d63fc38d6ee73dede4c5454c", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "id", "name" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000" }, "default_payment_term": { "type": "string", "nullable": true, "enum": [ "cash", "five_days", "seven_days", "fifteen_days", "thirty_days" ] }, "name": { "type": "string", "example": "Acme Supplies" }, "description": { "type": "string", "example": "Main office supplies provider", "nullable": true }, "payment_destination_class": { "description": "The Payment Instrument class this provider's payment reference serves; a payment through an instrument of another class never takes the reference.", "type": "string", "example": "crypto_wallet", "nullable": true, "enum": [ "cash", "bank_transfer", "mobile_payment", "point_of_sale", "zelle", "crypto_wallet", "check", "card" ] }, "payment_reference": { "properties": { "email": { "type": "string", "format": "email", "example": "provider@binance.com", "nullable": true } }, "type": "object", "nullable": true }, "fiscal_identity": { "properties": { "document_type": { "type": "string", "nullable": true, "enum": [ "rif", "cedula", "passport" ] }, "document_number": { "type": "string", "nullable": true, "maxLength": 32 }, "legal_name": { "type": "string", "nullable": true, "maxLength": 255 }, "fiscal_address": { "type": "string", "nullable": true, "maxLength": 500 }, "phone": { "type": "string", "nullable": true, "maxLength": 32 }, "email": { "type": "string", "format": "email", "nullable": true, "maxLength": 255 }, "vat_taxpayer_type": { "type": "string", "nullable": true, "enum": [ "ordinary", "formal", "non_taxpayer" ] }, "special_taxpayer_since": { "type": "string", "format": "date", "nullable": true }, "islr_person_type": { "type": "string", "nullable": true, "enum": [ "natural_resident", "natural_non_resident", "legal_domiciled", "legal_non_domiciled" ] } }, "type": "object", "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Provider created successfully" }, "409": { "description": "Duplicate provider ID or document", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "detail": { "type": "string" }, "error_code": { "type": "string", "example": "provider_document_already_registered" }, "existing_code": { "type": "string", "example": "PRV00001" } }, "type": "object" } } } }, "422": { "description": "Request or domain validation error", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string" }, "error_code": { "type": "string", "example": "invalid_rif", "nullable": true }, "errors": { "description": "Per-field messages; present on request validation failures and null on domain errors.", "type": "object", "nullable": true } }, "type": "object" } } } }, "403": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/contract-activations/lookup": { "get": { "tags": [ "Backoffice - Purchases - Activation Lookups" ], "summary": "Active activation codes of one active contract for child document selectors", "operationId": "e0df21f15b3bdf0352018d40e8f138e9", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "purchase_contract_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "Only id and code, scoped to company and parent", "content": { "application/json": { "schema": { "required": [ "items", "total", "per_page", "current_page" ], "properties": { "items": { "type": "array", "items": { "required": [ "id", "code" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" } }, "type": "object" } }, "total": { "type": "integer" }, "per_page": { "type": "integer" }, "current_page": { "type": "integer" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Company membership required" }, "422": { "description": "Invalid parent or pagination" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/contracts/lookup": { "get": { "tags": [ "Backoffice - Purchases - Purchase Contract Lookups" ], "summary": "Lookup Purchase Contracts for tenant forms", "operationId": "38f0435fb5a7cf92aab9483d5f8346b6", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending_approval", "active", "cancelled" ] } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 200, "minimum": 1 } } ], "responses": { "200": { "description": "Minimal Purchase Contract projection", "content": { "application/json": { "schema": { "properties": { "items": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "provider_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "pending_approval", "active", "cancelled" ] } }, "type": "object" } }, "total": { "type": "integer" }, "per_page": { "type": "integer" }, "current_page": { "type": "integer" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Not a member of this tenant" }, "404": { "description": "Tenant not found" }, "422": { "description": "Invalid status filter" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/purchases-invoices/lookup": { "get": { "tags": [ "Backoffice - Purchases - Invoice Lookups" ], "summary": "Invoice labels for tenant form selectors and filters", "operationId": "fc787c3c11c7c304fd43817a5c028127", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "ids[]", "in": "query", "schema": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 100 } }, { "name": "kinds[]", "in": "query", "description": "Defaults to regular and opening invoices; payable note codes can be named for history.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "regular", "opening", "debit_note" ] } } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "maximum": 200, "minimum": 1 } } ], "responses": { "200": { "description": "Minimal invoice labels; no amounts or audit metadata", "content": { "application/json": { "schema": { "required": [ "items", "total", "per_page", "current_page" ], "properties": { "items": { "type": "array", "items": { "required": [ "id", "code", "provider_name" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "provider_name": { "type": "string" } }, "type": "object" } }, "total": { "type": "integer" }, "per_page": { "type": "integer" }, "current_page": { "type": "integer" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Not a tenant member" }, "404": { "description": "Tenant not found" }, "422": { "description": "Invalid pagination" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/purchase-invoice-views": { "get": { "tags": [ "Backoffice - Purchase Invoice Views" ], "summary": "Search purchase invoice views with provider information", "operationId": "d9228ef2fb8e38b60396987a5e2292a5", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "provider_id", "in": "query", "description": "Scalar id or repeated provider_id[] values", "schema": { "type": "string" } }, { "name": "responsible_user_id", "in": "query", "description": "Scalar id or repeated responsible_user_id[] values", "schema": { "type": "string" } }, { "name": "purchase_contract_id", "in": "query", "description": "Filter by originating Purchase Contract ID", "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "description": "Scalar status or repeated status[] values. Scalar: to_be_approved, to_be_paid, partially_paid, fully_paid, cancelled, with_supplier_credit, applied or all; status[] takes the same values without all. The invoices proper and supplier debit notes hold to_be_approved, to_be_paid, partially_paid, fully_paid and cancelled; supplier credit notes hold to_be_approved, with_supplier_credit, applied and cancelled (MER-3292). A status none of the listed kinds holds answers an empty page, not an error.", "schema": { "type": "string" } }, { "name": "kind", "in": "query", "description": "Filter by document kind: regular (period documents), opening (Opening Documents), credit_note or debit_note (supplier notes). Omit to return the invoices proper (regular and opening); supplier credit and debit notes appear only when named (ADR 0216). Read from the query string only. credit_note also needs backoffice.purchases.credit-notes.view and debit_note backoffice.purchases.debit-notes.view, otherwise 403 (MER-3292). Legacy single-kind form of kinds[]: sending both answers 422 on kind.", "schema": { "type": "string", "enum": [ "regular", "opening", "credit_note", "debit_note" ] } }, { "name": "kinds[]", "in": "query", "description": "The document kinds to list (MER-3292), read from the query string only. Omitted, with no kind, only the invoices proper (regular and opening) are listed. credit_note also needs backoffice.purchases.credit-notes.view and debit_note backoffice.purchases.debit-notes.view, otherwise 403; an unknown kind answers 422 on kinds.N, and sending kind too answers 422 on kind. «Todos los documentos» sends regular, opening and each note kind the user may view.", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "regular", "opening", "credit_note", "debit_note" ] }, "minItems": 1 } }, { "name": "label_ids", "in": "query", "description": "Filter by assigned label ids", "schema": { "type": "array", "items": { "type": "string", "format": "uuid" } } }, { "name": "code", "in": "query", "schema": { "type": "string" } }, { "name": "name", "in": "query", "description": "Search in code and reference fields", "schema": { "type": "string" } }, { "name": "emission_date_from", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "emission_date_to", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "auto_approved", "in": "query", "description": "True returns only invoices the contract automation approved unattended; false returns every invoice it did not — including ones still awaiting approval. Combine with status to narrow further.", "schema": { "type": "boolean" } }, { "name": "auto_approved_from", "in": "query", "description": "Inclusive lower bound of the auto-approval period", "schema": { "type": "string", "format": "date" } }, { "name": "auto_approved_to", "in": "query", "description": "Inclusive upper bound of the auto-approval period; a bare date covers the whole day", "schema": { "type": "string", "format": "date" } }, { "name": "ids", "in": "query", "description": "Filter by specific invoice IDs", "schema": { "type": "array", "items": { "type": "string", "format": "uuid" } } }, { "name": "sort_by", "in": "query", "description": "A column of the document; anything else sorts by created_at. Ties go by code, then id, in the same direction, so pages never repeat or skip a row (MER-3292).", "schema": { "type": "string", "default": "created_at" } }, { "name": "sort_order", "in": "query", "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "group_by", "in": "query", "description": "status orders the displayed lifecycle groups before the requested sort and before pagination. Omit for ungrouped ordering.", "schema": { "type": "string", "enum": [ "status" ] } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 20 } } ], "responses": { "200": { "description": "List of purchase invoice views with provider information", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "provider_id": { "type": "string" }, "provider_name": { "type": "string" }, "provider_invoice_number": { "type": "string", "nullable": true }, "control_number": { "type": "string", "nullable": true }, "responsible_user_id": { "type": "string", "nullable": true }, "responsible_user_name": { "type": "string", "nullable": true }, "emission_date": { "type": "string", "format": "date" }, "total": { "type": "string", "example": "1160.00" }, "balance": { "type": "string", "example": "1160.00" }, "currency": { "description": "The Document Currency the amounts on this row are expressed in. Null on a row written before MER-2878 that the backfill has not reached; render the Company's functional currency then.", "type": "string", "example": "VES", "nullable": true, "enum": [ "USD", "VES" ] }, "registration_date": { "description": "The day the Company booked the invoice (ADR 0157).", "type": "string", "format": "date", "example": "2023-01-05", "nullable": true }, "functional_total": { "type": "string", "example": "1160.00", "nullable": true }, "reporting_total": { "type": "string", "example": "1160.00", "nullable": true }, "functional_balance": { "type": "string", "example": "1160.00", "nullable": true }, "reporting_balance": { "type": "string", "example": "1160.00", "nullable": true }, "status": { "type": "string" }, "kind": { "description": "Form flag: regular invoices go through approve/edit/cancel; opening documents settle through payments only (ADR 0179); credit_note and debit_note are supplier notes, listed only when the kind filter names them (ADR 0216).", "type": "string", "example": "regular", "enum": [ "regular", "opening", "credit_note", "debit_note" ] }, "purchase_contract_id": { "description": "Originating Purchase Contract, when this invoice was auto-generated from its Charges", "type": "string", "format": "uuid", "nullable": true }, "auto_approved_at": { "description": "When the nightly generator approved this invoice unattended, per its Purchase Contract's declared automation level; null when a human approved it or it is not yet approved", "type": "string", "format": "date-time", "nullable": true }, "origin_purchases_invoice_id": { "description": "The invoice a supplier note affects (MER-3292); null on an invoice row.", "type": "string", "format": "uuid", "nullable": true }, "origin_code": { "description": "The code of the invoice a supplier note affects; null on an invoice row, or when that invoice cannot be read.", "type": "string", "example": "PIN2600042", "nullable": true }, "is_credited": { "description": "«Con nota de crédito», derived and never stored: an invoice with at least one approved Supplier Credit Note (with_supplier_credit or applied), whatever note permissions the caller holds; always false on a note row. On a note row balance is the stored column: a cancelled credit note reads its full valuation, so render it as —.", "type": "boolean", "example": false }, "labels": { "description": "Labels assigned to this document, including supplier credit and debit notes, using each document kind's collaboration type.", "type": "array", "items": { "type": "object" } } }, "type": "object" } }, "meta": { "properties": { "total": { "type": "integer" }, "per_page": { "type": "integer" }, "current_page": { "type": "integer" }, "counts": { "description": "Documents per status, ignoring the status filter, zero-filled over every status the listed kinds hold: to_be_approved, to_be_paid, partially_paid, fully_paid and cancelled for the invoices proper and debit notes; to_be_approved, with_supplier_credit, applied and cancelled for credit notes. The default lists the five invoice statuses.", "type": "object", "additionalProperties": { "type": "integer" } }, "label_counts": { "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "403": { "description": "Without backoffice.purchases.purchases-invoices.view the route answers title Forbidden. With it, a kind naming a supplier note kind whose own view permission the caller lacks (backoffice.purchases.credit-notes.view or backoffice.purchases.debit-notes.view) answers title Unauthorized. Both carry status 403, error_code null and errors null: key on the status.", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unauthorized", "enum": [ "Forbidden", "Unauthorized" ] }, "status": { "type": "integer", "example": 403 }, "detail": { "type": "string", "example": "You do not have permission to access this resource." } }, "type": "object" } } } }, "422": { "description": "Validation error: an unknown kind or status, or kind sent together with kinds[]" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/last-item-price": { "get": { "tags": [ "Backoffice - Purchase Orders" ], "summary": "Last approved supplier price in the document currency and selected unit", "operationId": "getLastPurchaseItemPrice", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "provider_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "item_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "unit_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "currency", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 3, "minLength": 3 } } ], "responses": { "200": { "description": "No currency conversion; null when no eligible line exists", "content": { "application/json": { "schema": { "required": [ "unit_price" ], "properties": { "unit_price": { "type": "string", "nullable": true } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Requires purchase order or invoice create/update permission and company membership" }, "422": { "description": "Invalid query parameters" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/purchases-orders/{id}/approve": { "post": { "tags": [ "Backoffice - Purchase Orders" ], "summary": "Approve a purchase order", "operationId": "ae98669761fe5c45629a353ea329da55", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "financial_fingerprint": { "description": "Optional SHA-256 fingerprint accepting stored vs recalculated header differences", "type": "string", "pattern": "^[a-f0-9]{64}$", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Purchase order approved successfully" }, "422": { "description": "Order coverage validation failed, or historical difference acceptance required/stale (`error`, `detail`, `violations` and the acceptance fields). Or the order still awaits approval and its provider is inactive or no longer resolves in the company: a PurchaseOrderProblem with error_code `purchases_provider_inactive` or `purchases_provider_not_found` and `errors.provider_id`, checked after the items and the coverage (MER-5279). Only an order that awaits approval gets here: any other status answers 409 first. Nothing is approved.", "content": { "application/json": { "schema": { "anyOf": [ { "properties": { "error": { "type": "string", "example": "purchase_order_historical_difference_acceptance_required" }, "detail": { "type": "string" }, "violations": { "type": "array", "items": { "type": "object" } }, "financial_fingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "previous": { "type": "object" }, "proposed": { "type": "object" } }, "type": "object" }, { "$ref": "#/components/schemas/PurchaseOrderProblem" } ] } } } }, "400": { "description": "Bad request" }, "403": { "description": "Unauthorized" }, "404": { "description": "Purchase order not found" }, "409": { "description": "The purchase order no longer awaits approval: a PurchaseOrderProblem with error_code `purchase_order_cannot_be_modified`. The status answers before the items, the coverage and the provider (MER-5591). Nothing is approved. Or the email address is not verified (`message`).", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/PurchaseOrderProblem" }, { "$ref": "#/components/schemas/PurchaseOrderEmailNotVerified" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/purchases-orders/{id}/cancel": { "post": { "tags": [ "Backoffice - Purchase Orders" ], "summary": "Cancel a purchase order, optionally with its approved invoices", "description": "Cancels a purchase order «Por aprobar» or «Por facturar»; its inventory entry is reverted in the same transaction. An order that approved invoices billed («Facturada parcialmente» or «Facturada») answers 409 purchase_order_cannot_be_modified, and one «Por facturar» whose balance an approved invoice draws on answers 422 purchase_order_has_approved_invoices (MER-4961); both details say the order can be cancelled with its invoices. With `with_invoices: true` (MER-5525, ADR 0349) the order is cancelled together with its approved invoices in one transaction: each invoice is cancelled as `POST …/purchases-invoices/{id}/cancel` cancels it, with every refusal of that endpoint (paid, live notes, remitted withholdings, frozen fiscal periods, a revaluation that cannot be reverted), and then the order, whose entry reversal turns around what its receipts posted to In-Transit and to realized exchange (ADR 0347). A receipt that took an invoice's price into the stock refuses that invoice's own cancellation, but not this one, since its receipts are reverted with it. Any refusal writes nothing. `with_invoices: true` also requires `backoffice.purchases.purchases-invoices.cancel`; without it the answer is 403 before anything is read. Requires `backoffice.purchases.purchase-orders.cancel`.", "operationId": "b6155ee192b6bd1d71284db7489f414f", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "with_invoices": { "description": "Cancel the order together with its approved invoices in one step (MER-5525). Optional; absent or false cancels the order alone. A JSON boolean only (`boolean:strict`).", "type": "boolean", "example": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Purchase order cancelled successfully, with its approved invoices when `with_invoices` is true" }, "400": { "description": "With `with_invoices`, an invoice of the order that cannot be modified (purchases_invoice_cannot_be_modified)." }, "403": { "description": "Unauthorized: without `backoffice.purchases.purchase-orders.cancel`, or with `with_invoices: true` without `backoffice.purchases.purchases-invoices.cancel` (`error_code` null); nothing is read or written" }, "404": { "description": "Purchase order not found (purchase_order_not_found)" }, "409": { "description": "The order cannot be cancelled in its status (purchase_order_cannot_be_modified). An order approved invoices billed names `with_invoices` in its detail: «La orden de compra no se puede anular en estado: partially_invoiced. Tiene facturas de compra aprobadas: anúlala junto con sus facturas.». With `with_invoices`, an approved invoice of the order refuses its cancellation as `POST …/purchases-invoices/{id}/cancel` does — it is partially or fully paid (purchases_invoice_cannot_be_cancelled), it has notes that are not cancelled (purchases_invoice_has_live_notes, with `notes`), its VAT or ISLR withholding was remitted to SENIAT (remitted_withholding_requires_adjustment), a frozen fiscal period declared it or its VAT withholding (document_in_frozen_fiscal_period, with `fiscal_period`), or an Item it revalued moved while it waited for its locks (inventory_cost_revaluation_raced, send it again). Nothing is written.", "content": { "application/json": { "schema": { "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409, "enum": [ 409 ] }, "detail": { "type": "string", "example": "Solo se puede cancelar una factura de compra por aprobar o por pagar sin pagos aplicados." }, "error_code": { "type": "string", "enum": [ "purchase_order_cannot_be_modified", "purchases_invoice_cannot_be_cancelled", "purchases_invoice_has_live_notes", "remitted_withholding_requires_adjustment", "document_in_frozen_fiscal_period", "inventory_cost_revaluation_raced" ] }, "errors": { "type": "object", "example": null, "nullable": true }, "notes": { "description": "The notes to cancel first, in id order; only with purchases_invoice_has_live_notes.", "type": "array", "items": { "$ref": "#/components/schemas/PurchasesInvoiceLiveNote" } }, "fiscal_period": { "description": "Only on document_in_frozen_fiscal_period: the period whose current Declared Set holds the invoice.", "allOf": [ { "$ref": "#/components/schemas/FrozenFiscalPeriod" } ] } }, "type": "object" } } } }, "422": { "description": "Request validation failed (`with_invoices` not a JSON boolean, `errors` keyed by field); or the order is «Por facturar» but an approved purchases invoice already draws on its balance (purchase_order_has_approved_invoices, MER-4961): an invoice whose lines lost their link to the order spends the balance without moving the order to partially invoiced. Cancel those invoices first, or send `with_invoices: true`. With `with_invoices`, an opening invoice (purchases_invoice_opening_lifecycle_forbidden), an Item whose cost an invoice revalued that no longer holds the stock (inventory_cost_revaluation_cannot_be_reverted), or an entry whose reversal would take stock below zero (`error: inventory_entry_cannot_be_reverted`, with `violations`) also refuse. Nothing is written.", "content": { "application/json": { "schema": { "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422, "enum": [ 422 ] }, "detail": { "type": "string", "example": "La orden de compra no se puede anular: tiene facturas de compra aprobadas que consumen 116.00 USD de su saldo. Anula esas facturas primero, o anula la orden junto con sus facturas." }, "error_code": { "type": "string", "example": "purchase_order_has_approved_invoices", "nullable": true, "enum": [ "purchase_order_has_approved_invoices", "purchases_invoice_opening_lifecycle_forbidden", "inventory_cost_revaluation_cannot_be_reverted", null ] }, "errors": { "description": "Field-keyed validation messages for request validation (`with_invoices`); null otherwise.", "type": "object", "example": null, "nullable": true }, "purchase_order_code": { "description": "Only on purchase_order_has_approved_invoices.", "type": "string", "example": "POR2600011" }, "invoiced_amount": { "description": "Only on purchase_order_has_approved_invoices: the order total minus its balance, what approved invoices draw on it.", "type": "string", "pattern": "^\\d+\\.\\d{2}$", "example": "116.00" }, "currency": { "description": "Only on purchase_order_has_approved_invoices.", "type": "string", "example": "USD", "enum": [ "USD" ] } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/purchases-orders/{id}": { "get": { "tags": [ "Backoffice - Purchase Orders" ], "summary": "Get a purchase order by ID", "operationId": "bc780023bf4bed948ed647b3895960df", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Purchase order found", "content": { "application/json": { "schema": { "properties": { "created_at": { "description": "Persisted record creation timestamp in UTC; null only when unavailable.", "type": "string", "format": "date-time", "nullable": true }, "updated_at": { "description": "Persisted record update timestamp in UTC; null only when unavailable.", "type": "string", "format": "date-time", "nullable": true }, "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "provider_id": { "type": "string", "format": "uuid" }, "provider_name": { "description": "Stored provider name from the document company; null when unavailable.", "type": "string", "nullable": true }, "payment_term": { "type": "string" }, "emission_date": { "type": "string", "format": "date" }, "accounting_center_id": { "type": "string", "format": "uuid" }, "accounting_account_payable_id": { "type": "string", "format": "uuid" }, "location_id": { "type": "string", "format": "uuid", "nullable": true }, "status": { "type": "string" }, "reference": { "type": "string", "nullable": true }, "subtotal": { "type": "string" }, "discount": { "type": "string" }, "taxes": { "type": "string" }, "total": { "type": "string" }, "balance": { "type": "string", "nullable": true }, "observations": { "type": "string", "nullable": true }, "company_id": { "type": "string", "format": "uuid" }, "order_id": { "type": "string", "format": "uuid", "nullable": true }, "order_code": { "type": "string", "nullable": true }, "responsible_user_id": { "type": "string", "nullable": true }, "responsible_user_name": { "description": "Name of the responsible user while they are a member of the company that owns the purchase order; null when unassigned, when the id is not a positive integer, or when the user is not a member.", "type": "string", "nullable": true }, "items": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "category_id": { "type": "string", "format": "uuid" }, "item_id": { "type": "string", "format": "uuid" }, "quantity": { "type": "string" }, "unit_id": { "type": "string", "format": "uuid" }, "unit_price": { "type": "string" }, "subtotal": { "type": "string" }, "tax_id": { "type": "string", "format": "uuid" }, "tax_percentage": { "type": "string" }, "discount_percentage": { "type": "string" }, "accounting_center_id": { "type": "string", "format": "uuid" }, "accounting_account_id": { "type": "string", "format": "uuid" }, "order_item_id": { "type": "string", "format": "uuid", "nullable": true }, "pending_quantity": { "description": "Remaining quantity to be invoiced (formatted as string with 4 decimal places)", "type": "string" } }, "type": "object" } } }, "type": "object" } } } }, "403": { "description": "Unauthorized" }, "404": { "description": "Purchase order not found" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Backoffice - Purchase Orders" ], "summary": "Update a purchase order", "operationId": "81e0a0f32be94d63574ef8e24450ce1d", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "code", "provider_id", "payment_term", "emission_date", "accounting_center_id", "accounting_account_payable_id", "items" ], "properties": { "code": { "type": "string", "example": "PO-001" }, "provider_id": { "type": "string", "format": "uuid" }, "payment_term": { "type": "string", "example": "cash" }, "emission_date": { "type": "string", "format": "date" }, "accounting_center_id": { "type": "string", "format": "uuid" }, "accounting_account_payable_id": { "type": "string", "format": "uuid" }, "location_id": { "type": "string", "format": "uuid", "nullable": true }, "reference": { "type": "string", "nullable": true }, "observations": { "type": "string", "nullable": true }, "order_id": { "type": "string", "format": "uuid", "nullable": true }, "preview": { "description": "Optional scale-2 preview. String amounts only. Null skips the comparison.", "properties": { "subtotal": { "type": "string" }, "discount": { "type": "string" }, "taxes": { "type": "string" }, "total": { "type": "string" }, "tax_groups": { "type": "array", "items": { "properties": { "tax_id": { "type": "string", "format": "uuid" }, "tax_percentage": { "type": "string" }, "base": { "type": "string" }, "tax": { "type": "string" } }, "type": "object" } } }, "type": "object", "nullable": true }, "items": { "type": "array", "items": { "required": [ "id", "category_id", "item_id", "quantity", "unit_id", "unit_price", "tax_id", "tax_percentage", "discount_percentage", "accounting_center_id", "accounting_account_id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "category_id": { "type": "string", "format": "uuid" }, "item_id": { "type": "string", "format": "uuid" }, "quantity": { "type": "string", "example": "1.25" }, "unit_id": { "type": "string", "format": "uuid" }, "unit_price": { "type": "string", "example": "10.10" }, "tax_id": { "type": "string", "format": "uuid" }, "tax_percentage": { "type": "string", "example": "16.00" }, "discount_percentage": { "type": "string", "example": "10.00" }, "accounting_center_id": { "type": "string", "format": "uuid" }, "accounting_account_id": { "type": "string", "format": "uuid" }, "order_item_id": { "type": "string", "format": "uuid", "nullable": true } }, "type": "object" } } }, "type": "object" } } } }, "responses": { "200": { "description": "Purchase order updated successfully", "content": { "application/json": { "schema": { "type": "object" } } } }, "422": { "description": "Order coverage or link validation failed (`error`, `detail` and `violations`), or another globally rendered refusal keyed by `error`, such as `inactive_items_not_allowed` with `item_ids`. Or request validation failed (including an `items` that is not a JSON array), or a line names a category other than its item's or a unit its item does not have: a PurchaseOrderProblem, the latter with error_code `purchase_line_item_mismatch` and `errors` keyed by every refused line field, e.g. items.0.category_id or items.0.unit_id. A line that keeps an (item, category) pair the purchase order or its origin Order already stores is accepted after the item moves to another category; a unit has no such exemption. An inactive provider, or one the company does not have, is refused with error_code `purchases_provider_inactive` or `purchases_provider_not_found` and `errors.provider_id` (MER-5279). Nothing is saved.", "content": { "application/json": { "schema": { "anyOf": [ { "properties": { "error": { "type": "string" }, "detail": { "type": "string" }, "violations": { "type": "array", "items": { "type": "object" } } }, "type": "object" }, { "$ref": "#/components/schemas/PurchaseOrderProblem" } ] } } } }, "400": { "description": "Bad request" }, "403": { "description": "Unauthorized" }, "404": { "description": "Purchase order not found" }, "409": { "description": "The purchase order no longer awaits approval: a PurchaseOrderProblem with error_code `purchase_order_cannot_be_modified`. The status answers first, whatever else the request carries, and an edit that waited on an approval gets it too (MER-5591). Nothing is saved. Or the email address is not verified (`message`).", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/PurchaseOrderProblem" }, { "$ref": "#/components/schemas/PurchaseOrderEmailNotVerified" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/purchases-orders/item-defaults/{id}": { "get": { "tags": [ "Backoffice - Purchase Orders" ], "summary": "Read the item defaults needed to prepare a purchase order line", "operationId": "getPurchaseOrderItemDefaults", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Purchase line defaults only", "content": { "application/json": { "schema": { "required": [ "name", "category_id", "average_cost", "accounting_account_id" ], "properties": { "purchase_tax": { "description": "The Item purchase tax only when active in this company; otherwise null. Never a company fallback.", "required": [ "id", "name", "rate", "kind" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "rate": { "type": "string" }, "kind": { "type": "string" } }, "type": "object", "nullable": true }, "default_unit_id": { "description": "The configured purchase or sale unit for this document kind; null keeps the existing base/only-unit fallback.", "type": "string", "format": "uuid", "nullable": true }, "name": { "type": "string" }, "category_id": { "type": "string", "format": "uuid" }, "average_cost": { "description": "Proposed USD unit price: the average of the book kept in USD, the order's currency (the reporting book for a company with bolívar books); 0.0000 when no book is kept in USD.", "type": "string" }, "accounting_account_id": { "type": "string", "format": "uuid", "nullable": true } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Requires purchase order create or update permission and company membership" }, "404": { "description": "Item not found in this company" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/purchases-orders": { "get": { "tags": [ "Backoffice - Purchase Orders" ], "summary": "List purchase orders with pagination and filters", "operationId": "8ac49fccbf058b31b917740b8d672f10", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1 } }, { "name": "status", "in": "query", "description": "Scalar status, status=all, or repeated status[] values", "required": false, "schema": { "type": "string" } }, { "name": "provider_id", "in": "query", "description": "Scalar UUID or repeated provider_id[] values", "required": false, "schema": { "type": "string" } }, { "name": "responsible_user_id", "in": "query", "description": "Scalar id or repeated responsible_user_id[] values", "required": false, "schema": { "type": "string" } }, { "name": "location_id", "in": "query", "description": "Scalar UUID or repeated location_id[] values", "required": false, "schema": { "type": "string" } }, { "name": "label_ids", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 20 } }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "date_from", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "date_to", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "sort_by", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "emission_date", "code", "created_at", "status", "provider_id" ] } }, { "name": "sort_order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "group_by", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "status" ] } } ], "responses": { "200": { "description": "Purchase orders list", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "provider_id": { "type": "string", "format": "uuid" }, "provider_name": { "type": "string", "nullable": true }, "location_name": { "type": "string", "nullable": true }, "responsible_user_id": { "type": "string", "nullable": true }, "responsible_user_name": { "type": "string", "nullable": true }, "status": { "type": "string" }, "emission_date": { "type": "string", "format": "date" }, "total": { "type": "string" }, "balance": { "type": "string", "nullable": true }, "order_id": { "type": "string", "format": "uuid", "nullable": true }, "order_code": { "type": "string", "nullable": true }, "labels": { "type": "array", "items": { "type": "object" } } }, "type": "object" } }, "meta": { "properties": { "total": { "type": "integer" }, "per_page": { "type": "integer" }, "current_page": { "type": "integer" }, "counts": { "type": "object" }, "label_counts": { "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "403": { "description": "Unauthorized" }, "422": { "description": "Validation error" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Purchase Orders" ], "summary": "Create a new purchase order", "operationId": "ed436888a8b5f07bfc47a4934d83344c", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "id", "provider_id", "payment_term", "emission_date", "accounting_center_id", "accounting_account_payable_id", "items" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000" }, "provider_id": { "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174001" }, "payment_term": { "type": "string", "example": "30 days" }, "emission_date": { "type": "string", "format": "date", "example": "2023-12-01" }, "accounting_center_id": { "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174002" }, "accounting_account_payable_id": { "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174003" }, "location_id": { "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174004", "nullable": true }, "reference": { "type": "string", "example": "REF-001", "nullable": true }, "observations": { "type": "string", "example": "Special instructions", "nullable": true }, "order_id": { "type": "string", "format": "uuid", "nullable": true }, "responsible_user_id": { "description": "Optional company user id for the Purchase Order Responsable", "type": "string", "nullable": true }, "preview": { "description": "Optional scale-2 preview. String amounts only. Null skips the comparison.", "properties": { "subtotal": { "type": "string" }, "discount": { "type": "string" }, "taxes": { "type": "string" }, "total": { "type": "string" }, "tax_groups": { "type": "array", "items": { "properties": { "tax_id": { "type": "string", "format": "uuid" }, "tax_percentage": { "type": "string" }, "base": { "type": "string" }, "tax": { "type": "string" } }, "type": "object" } } }, "type": "object", "nullable": true }, "items": { "type": "array", "items": { "required": [ "id", "category_id", "item_id", "quantity", "unit_id", "unit_price", "tax_id", "tax_percentage", "discount_percentage", "accounting_center_id", "accounting_account_id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "category_id": { "type": "string", "format": "uuid" }, "item_id": { "type": "string", "format": "uuid" }, "quantity": { "type": "string", "example": "1.25" }, "unit_id": { "type": "string", "format": "uuid" }, "unit_price": { "type": "string", "example": "10.10" }, "tax_id": { "type": "string", "format": "uuid" }, "tax_percentage": { "type": "string", "example": "16.00" }, "discount_percentage": { "type": "string", "example": "10.00" }, "accounting_center_id": { "type": "string", "format": "uuid" }, "accounting_account_id": { "type": "string", "format": "uuid" }, "order_item_id": { "type": "string", "format": "uuid", "nullable": true } }, "type": "object" } } }, "type": "object" } } } }, "responses": { "201": { "description": "Purchase order created successfully", "content": { "application/json": { "schema": { "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "status": { "type": "string" } }, "type": "object" } } } }, "422": { "description": "Order coverage or link validation failed (`error`, `detail` and `violations`), or another globally rendered refusal keyed by `error`, such as `inactive_items_not_allowed` with `item_ids`. Or request validation failed (including an `items` that is not a JSON array), or a line names a category other than its item's or a unit its item does not have: a PurchaseOrderProblem, the latter with error_code `purchase_line_item_mismatch` and `errors` keyed by every refused line field, e.g. items.0.category_id or items.0.unit_id. A line that keeps an (item, category) pair the purchase order or its origin Order already stores is accepted after the item moves to another category; a unit has no such exemption. An inactive provider, or one the company does not have, is refused with error_code `purchases_provider_inactive` or `purchases_provider_not_found` and `errors.provider_id` (MER-5279). Nothing is saved.", "content": { "application/json": { "schema": { "anyOf": [ { "properties": { "error": { "type": "string" }, "detail": { "type": "string" }, "violations": { "type": "array", "items": { "type": "object" } } }, "type": "object" }, { "$ref": "#/components/schemas/PurchaseOrderProblem" } ] } } } }, "400": { "description": "Bad request" }, "403": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/purchases-orders/{id}/responsible": { "put": { "tags": [ "Backoffice - Purchase Orders" ], "summary": "Reassign the responsible user of a purchase order", "operationId": "42e44e9061ec60f204539a208745a0e6", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "responsible_user_id" ], "properties": { "responsible_user_id": { "description": "Company user id that becomes the Purchase Order Responsable; null clears it", "type": "string", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Responsible reassigned" }, "403": { "description": "Forbidden" }, "404": { "description": "Purchase order not found" }, "409": { "description": "Responsible cannot be reassigned in the current status" }, "422": { "description": "Validation error" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/purchases-orders/export": { "get": { "tags": [ "Backoffice - Purchase Orders" ], "summary": "Export órdenes de compra to XLSX", "description": "Exports all matching documents up to 5000 rows, ignoring pagination. Nonempty ids[] is an exclusive selection of at most 500 submitted UUIDs: every other filter is ignored, including invalid stale filters. Company isolation always applies. ", "operationId": "01b061f8c626bcc54c4c77bd1e4a7819", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "ids[]", "in": "query", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 500 } }, { "name": "status", "in": "query", "style": "form", "explode": true, "schema": { "type": "string", "enum": [ "pending_approval", "to_be_invoiced", "partially_invoiced", "fully_invoiced", "cancelled", "all" ] } }, { "name": "status[]", "in": "query", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "pending_approval", "to_be_invoiced", "partially_invoiced", "fully_invoiced", "cancelled" ] } } }, { "name": "provider_id", "in": "query", "style": "form", "explode": true, "schema": { "type": "string" } }, { "name": "provider_id[]", "in": "query", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" } } }, { "name": "responsible_user_id", "in": "query", "style": "form", "explode": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "responsible_user_id[]", "in": "query", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "label_ids[]", "in": "query", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 20 } }, { "name": "sort_order", "in": "query", "style": "form", "explode": true, "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "code", "in": "query", "style": "form", "explode": true, "schema": { "type": "string", "maxLength": 50 } }, { "name": "reference", "in": "query", "style": "form", "explode": true, "schema": { "type": "string", "maxLength": 255 } }, { "name": "search", "in": "query", "style": "form", "explode": true, "schema": { "type": "string", "maxLength": 255 } }, { "name": "search_query", "in": "query", "style": "form", "explode": true, "schema": { "type": "string", "maxLength": 255 } }, { "name": "date_from", "in": "query", "style": "form", "explode": true, "schema": { "type": "string", "format": "date" } }, { "name": "date_to", "in": "query", "style": "form", "explode": true, "schema": { "type": "string", "format": "date" } }, { "name": "location_id", "in": "query", "style": "form", "explode": true, "schema": { "type": "string" } }, { "name": "location_id[]", "in": "query", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" } } }, { "name": "group_by", "in": "query", "style": "form", "explode": true, "schema": { "type": "string", "enum": [ "status" ] } }, { "name": "sort_by", "in": "query", "style": "form", "explode": true, "schema": { "type": "string", "enum": [ "emission_date", "code", "created_at", "status", "provider_id" ] } } ], "responses": { "200": { "description": "XLSX attachment; an empty match returns a header-only sheet.", "headers": { "Cache-Control": { "description": "Always no-store: the workbook is never cached", "schema": { "type": "string", "example": "no-store, private" } } }, "content": { "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "format": "binary" } } } }, "403": { "description": "Missing backoffice.purchases.purchase-orders.view permission" }, "422": { "description": "Invalid active-mode query, more than 500 selected IDs or more than 5000 matching documents" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/purchases-invoices/{id}/accounting-readiness": { "get": { "tags": [ "Backoffice - Purchases Invoices" ], "summary": "Get accounting readiness for a purchases invoice", "description": "What keeps the invoice from approval. Its VAT account: a company that is not an ordinary VAT taxpayer on the invoice's registration date (Company Fiscal Profile and a formal or non_taxpayer Vigencia) debits its VAT to its non-deductible VAT account, so it misses NON_DEDUCTIBLE_VAT_ACCOUNT_MISSING (subject company, details [non_deductible_vat]) and never VAT_INPUT_ACCOUNT_MISSING (MER-5393); any other company under its fiscal profile misses VAT_INPUT_ACCOUNT_MISSING. Its VAT withholding reasons included (MER-3107) — VAT_WITHHOLDING_EXCLUSION_REQUIRED (subject provider, details [art3_n2_supplier_formal_taxpayer]) when the provider is a formal VAT taxpayer, since the readiness asks for no Withholding Reason and a formal taxpayer admits only an art. 3 exclusion, chosen in the approval (MER-5392) — and, for an ISLR withholding agent, its ISLR withholding reasons (MER-3700): ISLR_CLASSIFICATION_MISSING per unclassified line (subject invoice_item, details [items.{n}]), ISLR_PERSON_TYPE_MISSING (subject provider, details [islr_person_type]), ISLR_CONCEPT_NOT_ENABLED per line (subject invoice_item, details [items.{n}, {concept}:{person_type}, {disposition}]), RULE_NOT_IN_FORCE (details [{concept}:{person_type} or tax_unit, {date}]) and FISCAL_ACCOUNT_MISSING (details [islr_withholding_payable]); and, while it awaits approval, what the proposed rule would withhold from its VAT. Under a Company Fiscal Profile, an invoice that is not cancelled and carries VAT from a provider registered as a formal VAT taxpayer, who does not charge VAT, carries the non-blocking warning FORMAL_SUPPLIER_INVOICE_WITH_VAT (subject provider, details [formal]); a pending invoice reads the provider's current VAT Taxpayer Type, an approved one the type its approval froze (MER-5392).", "operationId": "21011671de6eb6ac9644ce25e0d47b7d", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Accounting readiness snapshot", "content": { "application/json": { "schema": { "properties": { "ready": { "type": "boolean" }, "missing": { "type": "array", "items": { "properties": { "reason_code": { "type": "string" }, "subject_type": { "type": "string" }, "subject_id": { "type": "string" }, "human_message": { "type": "string" }, "details": { "type": "array", "items": { "type": "string" } } }, "type": "object" } }, "warnings": { "$ref": "#/components/schemas/AccountingReadinessWarnings" }, "vat_withholding_proposal": { "$ref": "#/components/schemas/VatWithholdingProposal" } }, "type": "object" } } } }, "403": { "description": "Unauthorized" }, "404": { "description": "Purchases invoice not found" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/purchases-invoices/{id}/approve": { "post": { "tags": [ "Backoffice - Purchases Invoices" ], "summary": "Approve a purchases invoice", "description": "Approves a purchases invoice still to be approved. Under a Company Fiscal Profile, a company designated VAT withholding agent on the registration date withholds, in the same transaction, the rule's share of the VAT charged in bolívars (MER-3107): the standard 75 % unless `vat_withholding_reason` names an art. 5 cause (100 %) or an art. 3 exclusion (0 %), each with its supporting note; an exclusion also requires `backoffice.fiscal.withholdings.review`. A provider whose VAT Taxpayer Type is `formal` is never withheld from (PA SNAT/2025/000054 art. 3 n. 2, MER-5392): only an art. 3 exclusion is accepted, `art3_n2_supplier_formal_taxpayer` being the one the readiness proposes, and the standard rule or an art. 5 cause answers 422 accounting_configuration_incomplete with VAT_WITHHOLDING_EXCLUSION_REQUIRED; if the provider is in fact ordinary, correcting its VAT condition lets the approval freeze it and withhold the standard rule. The withholding relieves the supplier's debt, so the invoice owes its total less `withheld_amount`, and posts vat_withholding.determined crediting the vat_withholding_payable account. A withholding that withholds something also receives, in the same transaction, its numbered withholding certificate (MER-3108): `AAAAMM` of the company's today plus the next counter of its `vat_withholding` series; an exclusion at 0 % receives none. A company designated ISLR withholding agent on the registration date also withholds ISLR (MER-3700) once every line states its ISLR classification: one line per ISLR concept its lines pay, on the sum of their bases in bolívars, under the concept rule for the provider's ISLR Person Type and the Tax Unit in force; a concept whose base does not exceed its minimum withholds 0.00 with reason below_minimum. The ISLR withholding relieves the debt at the invoice's ratio of its base to its base in bolívars, adds to `withheld_amount` and posts islr_withholding.determined crediting the islr_withholding_payable account; one of zero is kept and posts nothing. Requires `backoffice.purchases.purchases-invoices.approve`.", "operationId": "024ef0c9bac2e4c9715f67909451a1ac", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "financial_fingerprint": { "description": "Optional SHA-256 of the current stored-versus-recalculated comparison. Required only when those amounts differ.", "type": "string", "pattern": "^[a-f0-9]{64}$", "nullable": true }, "vat_withholding_reason": { "description": "Optional Withholding Reason for the VAT withholding the approval determines (MER-3107). Omitted, null or code `standard` applies the standard rule.", "required": [ "code" ], "properties": { "code": { "description": "A rule code of the VAT withholding rates catalog in force on the registration date.", "type": "string", "pattern": "^[a-z0-9_]{1,64}$", "example": "art5_n1_missing_vat_breakdown" }, "note": { "description": "The note that supports an art. 3 or art. 5 cause; required by them.", "type": "string", "example": "La factura no discrimina el IVA.", "nullable": true, "maxLength": 500 } }, "type": "object", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Purchases invoice approved successfully" }, "400": { "description": "Cannot approve the purchases invoice, or (MER-5304) a draft of a purchase order no longer fits it: the order no longer takes invoices (purchase_order_cannot_be_invoiced) or a line bills more than is pending of its order line (invoice_quantity_exceeds_available); nothing is written." }, "403": { "description": "Unauthorized, or an art. 3 exclusion chosen without `backoffice.fiscal.withholdings.review` (error_code vat_withholding_exclusion_requires_review); nothing is written.", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Forbidden" }, "status": { "type": "integer", "example": 403 }, "detail": { "type": "string" }, "error_code": { "type": "string", "nullable": true, "enum": [ "vat_withholding_exclusion_requires_review" ] }, "errors": { "type": "object", "nullable": true } }, "type": "object" } } } }, "404": { "description": "Purchases invoice not found, or the purchase order of a draft is gone (purchase_order_not_found)" }, "409": { "description": "The invoice already has a VAT withholding (vat_withholding_already_determined) or an ISLR withholding (islr_withholding_already_determined), or the company's VAT or ISLR withholding certificate series reached its last number (certificate_sequence_exhausted); nothing is written. An Item the approval revalues moved its stock while it waited for its locks: inventory_cost_revaluation_raced (send it again).", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "detail": { "type": "string" }, "error_code": { "type": "string", "enum": [ "vat_withholding_already_determined", "islr_withholding_already_determined", "certificate_sequence_exhausted", "inventory_cost_revaluation_raced" ] }, "errors": { "type": "object", "nullable": true } }, "type": "object" } } } }, "422": { "description": "A certificate issued from the legal effective day requires the provider email; otherwise error_code withholding_provider_email_required with provider_id, provider_name and purchases_invoice_id (this invoice), and the whole approval rolls back. Request validation failed (`errors` keyed by field); stored amounts require acceptance or the supplied fingerprint is stale (`error` with `financial_fingerprint`, `previous` and `proposed`); the invoice cannot post, answered as {error: accounting_configuration_incomplete, missing: [{reason_code, subject_type, subject_id, human_message, details}]}, its VAT withholding reasons included (COMPANY_TAX_ATTRIBUTES_NOT_CONFIGURED, RULE_NOT_IN_FORCE, WITHHOLDING_REASON_REQUIRED, VAT_WITHHOLDING_EXCLUSION_REQUIRED on the provider with details [art3_n2_supplier_formal_taxpayer] when a formal taxpayer provider is asked anything but an art. 3 exclusion, FISCAL_ACCOUNT_MISSING with details [vat_withholding_payable]) and its ISLR withholding reasons (ISLR_CLASSIFICATION_MISSING on an invoice_item with details [items.{n}], ISLR_PERSON_TYPE_MISSING on the provider with details [islr_person_type], ISLR_CONCEPT_NOT_ENABLED on an invoice_item with details [items.{n}, {concept}:{person_type}, {disposition}], RULE_NOT_IN_FORCE with details [{concept}:{person_type} or tax_unit, {date}], FISCAL_ACCOUNT_MISSING with details [islr_withholding_payable]); an opening invoice or captured-amounts refusal (error_code purchases_invoice_opening_lifecycle_forbidden or purchases_invoice_captured_amounts_out_of_bound); a draft of a purchase order not in USD (error_code purchases_invoice_purchase_order_currency_mismatch, ADR 0326, with invoice_code, purchase_order_id, purchase_order_currency and invoice_currency) or with a line that bills no line of the order (error_code purchases_invoice_purchase_order_line_missing, MER-4961, with invoice_code, purchase_order_id and line_ids; a draft edited before MER-4961 lost every link and is cancelled and invoiced again), a line whose product or unit differs from its order line (purchases_invoice_line_does_not_match_purchase_order_line) or a line at another price than its order line without a reason (error_code purchases_invoice_line_price_difference_reason_required, MER-5304, its message under errors.items.{n}.price_difference_reason, with invoice_line_id, purchase_order_item_id, purchase_order_unit_price and purchase_order_discount_percentage), or a draft without a purchase order whose inventoriable line, billing no order line, posts to one of the company's inventory accounts, the asset accounts of its items or the Inventory In-Transit account (error_code purchase_invoice_inventory_account_without_receipt, MER-5277, its message under errors.items.{n}.accounting_account_id by stored line position), all checked before the stored-amounts acceptance, the accounting readiness and the rate selection; a line at another price that matches units the receipts of its order line brought first needs the inventory and cost of sales accounts of its inventoried item (ITEM_INVENTORY_ACCOUNT_MISSING, ITEM_COGS_ACCOUNT_MISSING on an inventory_item), since its approval puts the difference on their cost (ADR 0346); or the withholding cannot be determined (error_code company_tax_attributes_not_configured, rule_not_in_force, withholding_reason_required, vat_withholding_exclusion_required, invalid_vat_withholding_rate, islr_classification_missing, islr_person_type_missing or islr_concept_not_enabled). Nothing is written.", "content": { "application/json": { "schema": { "oneOf": [ { "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422, "enum": [ 422 ] }, "detail": { "type": "string", "example": "The given data was invalid." }, "error_code": { "description": "Null for request validation.", "type": "string", "example": null, "nullable": true }, "errors": { "description": "Field-keyed validation messages.", "type": "object", "example": { "financial_fingerprint": [ "The financial fingerprint format is invalid." ] }, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" }, { "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422, "enum": [ 422 ] }, "detail": { "type": "string" }, "error_code": { "description": "Non-null for mapped domain refusals from ApiController::handleException.", "type": "string", "enum": [ "company_tax_attributes_not_configured", "rule_not_in_force", "withholding_reason_required", "vat_withholding_exclusion_required", "invalid_vat_withholding_rate", "islr_classification_missing", "islr_person_type_missing", "islr_concept_not_enabled", "purchases_invoice_opening_lifecycle_forbidden", "purchases_invoice_captured_amounts_out_of_bound", "document_values_to_zero_in_both_books", "purchases_invoice_purchase_order_currency_mismatch", "purchases_invoice_purchase_order_line_missing", "purchases_invoice_line_does_not_match_purchase_order_line", "purchases_invoice_line_price_difference_reason_required", "purchase_invoice_inventory_account_without_receipt" ] }, "errors": { "type": "object", "example": null, "nullable": true } }, "type": "object" }, { "required": [ "error", "detail", "financial_fingerprint", "previous", "proposed" ], "properties": { "error": { "type": "string", "example": "purchases_invoice_historical_difference_acceptance_required", "enum": [ "purchases_invoice_historical_difference_acceptance_required", "purchases_invoice_historical_difference_acceptance_stale" ] }, "detail": { "type": "string" }, "financial_fingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "previous": { "properties": { "subtotal": { "type": "string", "example": "1.00" }, "discount": { "type": "string", "example": "0.00" }, "taxes": { "type": "string", "example": "0.00" }, "total": { "type": "string", "example": "1.00" } }, "type": "object" }, "proposed": { "properties": { "subtotal": { "type": "string", "example": "12.63" }, "discount": { "type": "string", "example": "1.26" }, "taxes": { "type": "string", "example": "1.82" }, "total": { "type": "string", "example": "13.19" } }, "type": "object" } }, "type": "object" }, { "description": "A withholding certificate issued from the PA SNAT/2026/00093 effective day requires the provider email (MER-5641, ADR 0352). Nothing is written.", "required": [ "title", "status", "detail", "error_code", "errors", "provider_id", "provider_name", "purchases_invoice_id" ], "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422, "enum": [ 422 ] }, "detail": { "type": "string", "example": "Completa el correo del proveedor Servicios Ejemplo, C.A. en su ficha antes de aprobar: el comprobante de retención lo requiere." }, "error_code": { "type": "string", "example": "withholding_provider_email_required", "enum": [ "withholding_provider_email_required" ] }, "errors": { "type": "object", "example": null, "nullable": true }, "provider_id": { "description": "The provider whose email is missing.", "type": "string", "format": "uuid" }, "provider_name": { "description": "The provider's legal name, or its id when it has none.", "type": "string", "example": "Servicios Ejemplo, C.A." }, "purchases_invoice_id": { "description": "The invoice whose certificate needs the email.", "type": "string", "format": "uuid" } }, "type": "object" }, { "required": [ "error", "missing" ], "properties": { "error": { "type": "string", "example": "accounting_configuration_incomplete", "enum": [ "accounting_configuration_incomplete" ] }, "missing": { "description": "Missing accounting or fiscal configuration entries.", "type": "array", "items": { "type": "object" } } }, "type": "object" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/purchases-invoices/bulk-approve": { "post": { "tags": [ "Backoffice - Purchases Invoices" ], "summary": "Bulk approve purchases invoices", "description": "Approves each requested invoice. Each one's VAT withholding is determined at the standard rule (MER-3107): a Withholding Reason is chosen only when approving one invoice, so a formal taxpayer provider's invoice, which admits only an art. 3 exclusion, reports VAT_WITHHOLDING_EXCLUSION_REQUIRED (MER-5392). Each withholding receives its numbered withholding certificate in the same transaction (MER-3108), numbered in the order the invoices are approved. When any invoice cannot post, nothing is approved and the answer is 422 accounting_configuration_incomplete per invoice, its VAT withholding reasons included (COMPANY_TAX_ATTRIBUTES_NOT_CONFIGURED, RULE_NOT_IN_FORCE, VAT_WITHHOLDING_EXCLUSION_REQUIRED on the provider with details [art3_n2_supplier_formal_taxpayer], FISCAL_ACCOUNT_MISSING with details [vat_withholding_payable]) and its ISLR withholding reasons for an ISLR withholding agent (ISLR_CLASSIFICATION_MISSING, ISLR_PERSON_TYPE_MISSING, ISLR_CONCEPT_NOT_ENABLED, RULE_NOT_IN_FORCE with details [{concept}:{person_type} or tax_unit, {date}], FISCAL_ACCOUNT_MISSING with details [islr_withholding_payable]). Each invoice's ISLR withholding is determined after its VAT withholding, in the same transaction (MER-3700).", "operationId": "a7f6de8c524461372c5afdf95e0340fd", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "ids": { "description": "Array of invoice IDs to approve", "type": "array", "items": { "type": "string" } } }, "type": "object" } } } }, "responses": { "200": { "description": "Bulk approval completed", "content": { "application/json": { "schema": { "properties": { "success_count": { "type": "integer" }, "failed_count": { "type": "integer" }, "review_needed_count": { "type": "integer" }, "failures": { "type": "array", "items": { "properties": { "invoice_id": { "type": "string" }, "invoice_code": { "type": "string" }, "error": { "type": "string" } }, "type": "object" } }, "review_needed": { "type": "array", "items": { "properties": { "invoice_id": { "type": "string" }, "invoice_code": { "type": "string" }, "error_code": { "type": "string", "example": "purchases_invoice_historical_difference_acceptance_required" }, "error": { "type": "string" }, "financial_fingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "previous": { "properties": { "subtotal": { "type": "string" }, "discount": { "type": "string" }, "taxes": { "type": "string" }, "total": { "type": "string" } }, "type": "object" }, "proposed": { "properties": { "subtotal": { "type": "string" }, "discount": { "type": "string" }, "taxes": { "type": "string" }, "total": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "type": "object" } } } }, "403": { "description": "Unauthorized" }, "409": { "description": "An invoice already has a VAT withholding (vat_withholding_already_determined) or an ISLR withholding (islr_withholding_already_determined), or the company's VAT or ISLR withholding certificate series reached its last number (certificate_sequence_exhausted); nothing is written. An Item the approval revalues moved its stock while it waited for its locks: inventory_cost_revaluation_raced (send it again).", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "detail": { "type": "string" }, "error_code": { "type": "string", "enum": [ "vat_withholding_already_determined", "islr_withholding_already_determined", "certificate_sequence_exhausted", "inventory_cost_revaluation_raced" ] }, "errors": { "type": "object", "nullable": true } }, "type": "object" } } } }, "422": { "description": "A certificate issued from the legal effective day requires the provider email; otherwise error_code withholding_provider_email_required with provider_id, provider_name and purchases_invoice_id (the requested invoice that failed), and the whole batch rolls back, the invoices that would have approved included. Request validation failed (`errors` keyed by field); an invoice cannot post (accounting_configuration_incomplete per invoice), or its VAT or ISLR withholding cannot be determined (error_code company_tax_attributes_not_configured, rule_not_in_force, vat_withholding_exclusion_required, invalid_vat_withholding_rate, islr_classification_missing, islr_person_type_missing or islr_concept_not_enabled); or one requested draft of a purchase order is not in USD (error_code purchases_invoice_purchase_order_currency_mismatch, ADR 0326, with purchase_order_id, purchase_order_currency and invoice_currency) or has a line that bills no line of the order (error_code purchases_invoice_purchase_order_line_missing, MER-4961, with purchase_order_id and line_ids), either of which refuses the whole batch and names that draft in invoice_code; or a requested draft of a purchase order has a line whose product or unit differs from its order line (purchases_invoice_line_does_not_match_purchase_order_line) or a line at another price than its order line without a reason (purchases_invoice_line_price_difference_reason_required, MER-5304, its message under errors.items.{n}.price_difference_reason, with invoice_line_id, purchase_order_item_id, purchase_order_unit_price and purchase_order_discount_percentage), or a requested draft without a purchase order has an inventoriable line, billing no order line, posted to one of the company's inventory accounts, the asset accounts of its items or the Inventory In-Transit account (error_code purchase_invoice_inventory_account_without_receipt, MER-5277, its message under errors.items.{n}.accounting_account_id), which refuses the whole batch too. Nothing is written.", "content": { "application/json": { "schema": { "oneOf": [ { "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422, "enum": [ 422 ] }, "detail": { "type": "string", "example": "The given data was invalid." }, "error_code": { "description": "Null for request validation.", "type": "string", "example": null, "nullable": true }, "errors": { "description": "Field-keyed validation messages.", "type": "object", "example": { "ids": [ "The ids field is required." ] }, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" }, { "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422, "enum": [ 422 ] }, "detail": { "type": "string" }, "error_code": { "description": "Domain refusal answered as Problem JSON via ApiController::handleException.", "type": "string", "enum": [ "company_tax_attributes_not_configured", "rule_not_in_force", "withholding_reason_required", "vat_withholding_exclusion_required", "invalid_vat_withholding_rate", "islr_classification_missing", "islr_person_type_missing", "islr_concept_not_enabled", "purchases_invoice_captured_amounts_out_of_bound", "document_values_to_zero_in_both_books", "purchases_invoice_purchase_order_currency_mismatch", "purchases_invoice_purchase_order_line_missing", "purchases_invoice_line_does_not_match_purchase_order_line", "purchases_invoice_line_price_difference_reason_required", "purchase_invoice_inventory_account_without_receipt" ] }, "errors": { "type": "object", "example": null, "nullable": true } }, "type": "object" }, { "description": "A withholding certificate issued from the PA SNAT/2026/00093 effective day requires the provider email (MER-5641, ADR 0352). Nothing is written.", "required": [ "title", "status", "detail", "error_code", "errors", "provider_id", "provider_name", "purchases_invoice_id" ], "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422, "enum": [ 422 ] }, "detail": { "type": "string", "example": "Completa el correo del proveedor Servicios Ejemplo, C.A. en su ficha antes de aprobar: el comprobante de retención lo requiere." }, "error_code": { "type": "string", "example": "withholding_provider_email_required", "enum": [ "withholding_provider_email_required" ] }, "errors": { "type": "object", "example": null, "nullable": true }, "provider_id": { "description": "The provider whose email is missing.", "type": "string", "format": "uuid" }, "provider_name": { "description": "The provider's legal name, or its id when it has none.", "type": "string", "example": "Servicios Ejemplo, C.A." }, "purchases_invoice_id": { "description": "The requested invoice whose certificate needs the email; the client names it from the ids it sent.", "type": "string", "format": "uuid" } }, "type": "object" }, { "required": [ "error", "missing" ], "properties": { "error": { "type": "string", "example": "accounting_configuration_incomplete", "enum": [ "accounting_configuration_incomplete" ] }, "missing": { "description": "Per-invoice missing accounting configuration entries.", "type": "array", "items": { "type": "object" } } }, "type": "object" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/purchases-invoices/bulk-cancel": { "post": { "tags": [ "Backoffice - Purchases Invoices" ], "summary": "Bulk cancel purchases invoices", "description": "Cancels each requested invoice in its own savepoint, in ascending id order. An invoice that cannot be cancelled is one item of `failures` and nothing of it is written, while the rest of the batch goes on; an invoice with Supplier Credit or Debit Notes that are not cancelled, drafts included, fails with an `error` naming those notes, and a partially or fully paid invoice fails with its Spanish refusal as `error`. An invoice to be paid with a practised VAT withholding voids it in cascade inside its own savepoint (MER-3110, ADR 0196): the withholding and its certificate, which keeps its number, become `voided` with the reason «Factura cancelada», the debt is restored and `vat_withholding.voided` posts; a voiding that fails is that invoice's failure and leaves it uncancelled. An invoice whose VAT withholding was remitted to SENIAT fails with an `error` naming its code — «La factura de compra {code} tiene una retención de IVA enterada al SENIAT. No se puede cancelar: corrígela con una nota y un ajuste de la retención (art. 12).» (MER-3111). An invoice to be paid with a practised ISLR withholding voids it too, after its VAT withholding and inside the same savepoint (MER-3702): the withholding and its certificate, which keeps its number, become `voided` with the reason «Factura cancelada», the debt is restored and `islr_withholding.voided` posts unless it relieved no cent of either book; an invoice whose ISLR withholding was remitted to SENIAT fails with an `error` naming its code — «La factura de compra {code} tiene una retención de ISLR enterada al SENIAT. No se puede cancelar: corrígela con una nota y un ajuste de la retención en un período posterior.» — or, when both its withholdings were remitted, naming both taxes (MER-3703). Every invoice is checked before any is locked: one the current Declared Set of a Fiscal Period in review or closed holds fails with error_code document_in_frozen_fiscal_period and the Spanish `error` naming the period, and nothing of it is written; so does one to be paid whose standing VAT withholding a frozen period declared (MER-3837). Every failure carries the refusal's `error_code`, null for an invoice not found or an unexpected failure. A broken invariant of stored data is no item's failure: it rolls the whole batch back and answers 500. A lost race retries the whole batch. Requires `backoffice.purchases.purchases-invoices.cancel`.", "operationId": "a14a97eb7a7cebc38766a1b0bc47e316", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "ids": { "description": "Array of invoice IDs to cancel", "type": "array", "items": { "type": "string" } } }, "type": "object" } } } }, "responses": { "200": { "description": "Bulk cancellation completed", "content": { "application/json": { "schema": { "properties": { "success_count": { "type": "integer" }, "failed_count": { "type": "integer" }, "failures": { "type": "array", "items": { "properties": { "invoice_id": { "type": "string" }, "invoice_code": { "type": "string" }, "error": { "description": "The refusal's message; Spanish for a business refusal", "type": "string" }, "error_code": { "description": "The refusal's code, such as document_in_frozen_fiscal_period, purchases_invoice_has_live_notes, purchases_invoice_cannot_be_cancelled, remitted_withholding_requires_adjustment or purchases_invoice_price_taken_by_receipt (MER-5525: a receipt of its Purchase Order priced its goods at it, so it is cancelled only with its order); null for an invoice not found or an unexpected failure (MER-3837).", "type": "string", "example": "document_in_frozen_fiscal_period", "nullable": true } }, "type": "object" } } }, "type": "object" } } } }, "403": { "description": "Unauthorized" }, "422": { "description": "Request validation failed (`errors` keyed by field)", "content": { "application/json": { "schema": { "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422, "enum": [ 422 ] }, "detail": { "type": "string", "example": "The given data was invalid." }, "error_code": { "description": "Null for request validation.", "type": "string", "example": null, "nullable": true }, "errors": { "description": "Field-keyed validation messages (for example `ids` or `ids.0`).", "type": "object", "example": { "ids": [ "The ids field is required." ] }, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" } } } }, "500": { "description": "A broken invariant of stored data, such as a document declared outside a frozen period's current set (declared_document_outside_frozen_period), fails the whole request instead of one item: nothing of the batch is written (MER-3837)" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/purchases-invoices/bulk-pay": { "post": { "tags": [ "Backoffice - Purchases Invoices" ], "summary": "Bulk create payments for purchases invoices", "description": "Creates one payment to be approved per invoice, for its whole balance, through one payment instrument in any currency. The instrument is checked once before any invoice is read, so an instrument that cannot carry a payment fails the whole request and writes nothing. Each payment takes the provider's own payment reference instead of `method_reference` when the provider's `payment_destination_class` is the instrument's class and the provider has a reference. An invoice in the instrument's currency is paid unit for unit. An invoice in another currency is paid with the units its balance converts into (MER-3128): USD and VES at the official rate known now, the last one published even when it is stale (the payment takes its own rate when it is applied); USDT at the settlement terms of the invoice's own provider. The units are the conversion of the balance rounded half-up once, one cent less when they would derive more than the balance beyond one cent; within that cent the payment settles the whole balance, otherwise it settles what its units derive (stated as its payable and `amount_paid`) and the rest stays open. An invoice whose balance cannot be converted is listed in `failures` with a Spanish `error` and the rest are paid: the provider has no USDT terms for the invoice's currency, the pair does not convert for this company, no official rate was ever published, or the balance is worth less than one cent of the instrument's currency. `ids` are paid once each, by ascending id, so `failures` follow that order. Amounts are never sent: the server is authoritative, and a rate published after the client's estimate changes the units.", "operationId": "e788b1ef5405ad70b77b144e20c3d55f", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "ids", "instrument_id", "date_payment" ], "properties": { "ids": { "description": "The invoices to pay", "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1 }, "instrument_id": { "description": "An active payment instrument of the company, in any currency, whose treasury account is active (GET /treasury/payment-instruments/lookup). Invoices in another currency are paid with the units their balance converts into.", "type": "string", "format": "uuid" }, "method_reference": { "description": "Optional payment reference for every payment, e.g. `email` for a crypto wallet instrument.", "type": "object", "example": { "email": "provider@example.com" }, "nullable": true, "additionalProperties": true }, "date_payment": { "description": "Validated as a date; the API stores and returns Y-m-d. It never chooses the rate an invoice in another currency is converted at.", "type": "string", "format": "date" } }, "type": "object" } } } }, "responses": { "200": { "description": "Bulk payment creation completed", "content": { "application/json": { "schema": { "properties": { "success_count": { "type": "integer" }, "failed_count": { "type": "integer" }, "review_needed_count": { "description": "Always 0: bulk pay needs no review.", "type": "integer" }, "failures": { "description": "By ascending invoice_id. Show `error` as it is; never parse it.", "type": "array", "items": { "properties": { "invoice_id": { "type": "string" }, "invoice_code": { "type": "string" }, "error": { "type": "string", "example": "La factura está en VES y el instrumento de pago en USD: esa moneda no se convierte a la de la factura" } }, "type": "object" } }, "review_needed": { "description": "Always empty: bulk pay needs no review. Shared shape with bulk approve.", "type": "array", "items": { "properties": { "invoice_id": { "type": "string" }, "invoice_code": { "type": "string" }, "error_code": { "type": "string" }, "error": { "type": "string" }, "financial_fingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "previous": { "properties": { "subtotal": { "type": "string" }, "discount": { "type": "string" }, "taxes": { "type": "string" }, "total": { "type": "string" } }, "type": "object" }, "proposed": { "properties": { "subtotal": { "type": "string" }, "discount": { "type": "string" }, "taxes": { "type": "string" }, "total": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "type": "object" } } } }, "403": { "description": "Unauthorized" }, "404": { "description": "payment_method_instrument_not_found: the payment instrument does not exist or belongs to another company (same body for both). Nothing is written." }, "422": { "description": "The body is invalid (`errors` names each field); or `error_code` is payment_method_instrument_inactive or payment_method_instrument_treasury_account_inactive. Nothing is written." }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/purchases-invoices/{id}/cancel": { "post": { "tags": [ "Backoffice - Purchases Invoices" ], "summary": "Cancel a purchases invoice", "description": "Cancels a purchases invoice still to be approved or to be paid. An invoice the current Declared Set of a Fiscal Period in review or closed holds answers 409 document_in_frozen_fiscal_period first, before anything is locked, naming the period in `fiscal_period`; so does one to be paid whose standing VAT withholding a frozen period declared, checked after the remitted withholdings, since the cancellation would void it (MER-3837). An invoice with Supplier Credit or Debit Notes that are not cancelled, drafts included, answers 409 purchases_invoice_has_live_notes naming them in `notes`, checked before its status, so an invoice a note relieved names its notes rather than answering purchases_invoice_cannot_be_cancelled; once its notes are cancelled it cancels as usual. An invoice to be paid with a practised VAT withholding voids it in cascade, in the same transaction (MER-3110, ADR 0196): the withholding and its certificate, which keeps its number, become `voided` with the reason «Factura cancelada», the debt it relieved is restored, `vat_withholding.voided` posts inverting its entry in both books and the voiding is audited with whoever cancelled; if any of it fails, the invoice is not cancelled. An invoice whose VAT withholding was remitted to SENIAT answers 409 remitted_withholding_requires_adjustment, with a Spanish `detail` naming the invoice's code, since a remitted withholding is corrected with a note and an adjustment under art. 12 (MER-3111). An invoice to be paid with a practised ISLR withholding, one of zero included, voids it too, after its VAT withholding and in the same transaction (MER-3702, ADR 0196): the withholding and its certificate, which keeps its number, become `voided` with the reason «Factura cancelada», the debt it relieved is restored, `islr_withholding.voided` posts inverting its entry in both books (one that relieved no cent of either book posted nothing and reverses nothing) and the voiding is audited with whoever cancelled. An invoice to be paid whose ISLR withholding was remitted to SENIAT (MER-3703), even one whose share of the document rounded below a cent, answers 409 remitted_withholding_requires_adjustment with a Spanish `detail` naming the invoice's code and the tax, since it is corrected with a note and an adjustment in a later period; when both its VAT and its ISLR withholdings were remitted, the detail names both. Nothing is written. A partially or fully paid invoice answers 409 purchases_invoice_cannot_be_cancelled. An invoice whose lines at another price than their purchase order put the difference on the cost of received goods (MER-5304, ADR 0346) also reverts that Inventory Cost Revaluation: each Item gives back the share it put on hand, or takes back the share a lower price took off, and `inventory_cost.revaluation_reverted` inverts the `inventory_cost.revalued` entry; while an Item no longer holds stock carrying that share, it answers 422 inventory_cost_revaluation_cannot_be_reverted and writes nothing. An invoice of a Purchase Order approved before its goods arrived left them on Inventory In-Transit at its dollars; once a receipt of its order line priced them at it into the stock (ADR 0344), it is not cancelled alone (MER-5525, ADR 0349): it answers 422 purchases_invoice_price_taken_by_receipt with `purchase_order_id` and `item_id`, and writes nothing; cancel its order with its invoices instead (`POST …/purchases-orders/{id}/cancel` with `with_invoices: true`). An invoice whose receipts came before it is cancelled as usual. An invoice approved before MER-5525 is refused once a receipt of its order line posted after its approval. Cancelling again answers 200. Requires `backoffice.purchases.purchases-invoices.cancel`.", "operationId": "7ecb4f1a69712499e12e58420572087a", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Purchases invoice cancelled successfully, or already cancelled" }, "403": { "description": "Unauthorized" }, "404": { "description": "Purchases invoice not found (purchases_invoice_not_found), also for a note's id" }, "409": { "description": "The invoice has notes that are not cancelled, drafts included (purchases_invoice_has_live_notes, with `notes` in id order), its VAT withholding was remitted to SENIAT (remitted_withholding_requires_adjustment, detail: La factura de compra {code} tiene una retención de IVA enterada al SENIAT. No se puede cancelar: corrígela con una nota y un ajuste de la retención (art. 12).), its ISLR withholding was remitted (remitted_withholding_requires_adjustment, detail: La factura de compra {code} tiene una retención de ISLR enterada al SENIAT. No se puede cancelar: corrígela con una nota y un ajuste de la retención en un período posterior.; when both were remitted: La factura de compra {code} tiene retenciones de IVA e ISLR enteradas al SENIAT. No se puede cancelar: corrígela con una nota y un ajuste de cada retención (IVA: art. 12; ISLR: en un período posterior).), or it is partially or fully paid (purchases_invoice_cannot_be_cancelled, detail: Solo se puede cancelar una factura de compra por aprobar o por pagar sin pagos aplicados.), or a frozen fiscal period declared it or its VAT withholding (document_in_frozen_fiscal_period, with `fiscal_period`); only purchases_invoice_has_live_notes carries `notes`, only document_in_frozen_fiscal_period carries `fiscal_period`, and nothing is written. An Item whose revaluation the cancellation reverts, or whose receipts it reads, moved its stock while it waited for its locks: inventory_cost_revaluation_raced (send it again).", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "detail": { "type": "string", "example": "La factura de compra PIN26000012 tiene notas vigentes (NCP2600001, NCP2600002). Para cancelarla, primero cancela esas notas." }, "error_code": { "type": "string", "enum": [ "purchases_invoice_has_live_notes", "purchases_invoice_cannot_be_cancelled", "remitted_withholding_requires_adjustment", "document_in_frozen_fiscal_period" ] }, "errors": { "type": "object", "nullable": true }, "notes": { "description": "The notes to cancel first, in id order; only with purchases_invoice_has_live_notes.", "type": "array", "items": { "$ref": "#/components/schemas/PurchasesInvoiceLiveNote" } }, "fiscal_period": { "description": "Only on document_in_frozen_fiscal_period: the period whose current Declared Set holds the document.", "allOf": [ { "$ref": "#/components/schemas/FrozenFiscalPeriod" } ] } }, "type": "object" } } } }, "422": { "description": "An opening document is never cancelled here (purchases_invoice_opening_lifecycle_forbidden), an Item whose cost the invoice revalued no longer holds stock carrying that share (inventory_cost_revaluation_cannot_be_reverted, MER-5304), or a receipt of its Purchase Order took the price it left on In-Transit into the stock (purchases_invoice_price_taken_by_receipt, MER-5525, ADR 0349; detail: Una recepción de su orden de compra ya llevó al costo del inventario el precio de esta factura, así que no se puede anular sola. Anula la orden de compra junto con sus facturas.), which carries `purchase_order_id` and `item_id` so the client can offer to cancel that order with its invoices; nothing is written.", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string" }, "error_code": { "type": "string", "enum": [ "purchases_invoice_opening_lifecycle_forbidden", "inventory_cost_revaluation_cannot_be_reverted", "purchases_invoice_price_taken_by_receipt" ] }, "errors": { "type": "object", "nullable": true }, "purchase_order_id": { "description": "Only on purchases_invoice_price_taken_by_receipt: the order to cancel with its invoices.", "type": "string", "format": "uuid" }, "item_id": { "description": "Only on purchases_invoice_price_taken_by_receipt: the Item whose cost a receipt priced at the invoice.", "type": "string" } }, "type": "object" } } } }, "500": { "description": "The cancellation could not be persisted, nor the voiding of its VAT or ISLR withholding (vat_withholding_posted_transaction_missing, islr_withholding_posted_transaction_missing, transaction_already_reversed or purchases_invoice_withholding_restore_failed among others)" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/purchases-invoices/{id}/capture-discrepancy/accept": { "post": { "tags": [ "Backoffice - Purchases Invoices" ], "summary": "Accept an out-of-bound capture discrepancy", "operationId": "da7f3e2b93d21ef3cb55de4da009a474", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "reason", "fingerprint" ], "properties": { "reason": { "description": "Mandatory justification for accepting the capture discrepancy.", "type": "string", "maxLength": 500, "minLength": 1 }, "fingerprint": { "description": "SHA-256 of the current out-of-bound capture discrepancy assessment.", "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "type": "object" } } } }, "responses": { "200": { "description": "Capture discrepancy accepted" }, "403": { "description": "Unauthorized" }, "404": { "description": "Purchases invoice not found" }, "409": { "description": "Fingerprint is stale" }, "422": { "description": "Reason missing/invalid, no active OOB discrepancy, or wrong status" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/purchases-invoices/{id}/credit-applications": { "get": { "tags": [ "Backoffice - Purchases Invoices" ], "summary": "List the credit applications that relieved a purchases invoice", "description": "Every credit-note and supplier-advance application that relieved the purchases invoice, live and reverted, by date then the order they were recorded (MER-4719). An invoice is relieved by a bounded number of applications, so the list is not paginated. Unapply stays at the source; this endpoint is read-only. Requires backoffice.purchases.purchases-invoices.view.", "operationId": "listPurchasesInvoiceCreditApplications", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The invoice's relieving applications, empty when it has none", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupplierCreditApplicationList" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks backoffice.purchases.purchases-invoices.view" }, "404": { "description": "purchases_invoice_not_found: the invoice does not exist or belongs to another company, also for a note or debit id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupplierCreditApplicationProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/purchases-invoices/{id}/fiscal-credit": { "put": { "tags": [ "Backoffice - Purchases Invoices" ], "summary": "Change a draft purchase invoice fiscal credit mark", "operationId": "d04bd27ea6408926caeddafcec8c6afe", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "without_fiscal_credit" ], "properties": { "without_fiscal_credit": { "type": "boolean" }, "no_fiscal_credit_reason": { "type": "string", "nullable": true, "enum": [ "buyer_not_identified", "contingency_copy", "formal_requirements", "other" ] }, "no_fiscal_credit_note": { "type": "string", "nullable": true, "maxLength": 500 } }, "type": "object" } } } }, "responses": { "200": { "description": "Fiscal credit mark updated" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "404": { "description": "Invoice not found" }, "422": { "description": "Invalid mark, approved invoice or request validation failure. Non-deductible VAT of inventory is capitalized in its acquisition cost." }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/purchases-invoices/{id}": { "get": { "tags": [ "Backoffice - Purchases Invoices" ], "summary": "Get a purchases invoice by ID", "operationId": "ade9177a9e0a6f2e77c850742104e258", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Purchases invoice details", "content": { "application/json": { "schema": { "properties": { "created_at": { "description": "Persisted record creation timestamp in UTC; null only when unavailable.", "type": "string", "format": "date-time", "nullable": true }, "updated_at": { "description": "Persisted record update timestamp in UTC; null only when unavailable.", "type": "string", "format": "date-time", "nullable": true }, "id": { "type": "string" }, "code": { "type": "string" }, "provider_id": { "type": "string" }, "provider_name": { "description": "Stored provider name from the document company; null when unavailable.", "type": "string", "nullable": true }, "payment_term": { "type": "string", "example": "cash", "enum": [ "cash", "five_days", "seven_days", "fifteen_days", "thirty_days" ] }, "emission_date": { "type": "string", "format": "date" }, "accounting_center_id": { "type": "string" }, "accounting_account_payable_id": { "type": "string" }, "location_id": { "type": "string", "nullable": true }, "status": { "type": "string" }, "kind": { "description": "Form flag: regular invoices go through approve/edit/cancel; opening documents settle through payments only (ADR 0179).", "type": "string", "example": "regular", "enum": [ "regular", "opening" ] }, "reference": { "type": "string", "nullable": true }, "subtotal": { "type": "string", "example": "1000.00" }, "discount": { "type": "string", "example": "0.00" }, "taxes": { "type": "string", "example": "160.00" }, "total": { "type": "string", "example": "1160.00" }, "balance": { "description": "What the invoice still owes, in its Document Currency.", "type": "string", "example": "1160.00" }, "withheld_amount": { "description": "What practised withholdings withheld from the invoice, in its Document Currency (MER-3107): the provider is owed the total less this amount. 0.00 when nothing was withheld.", "type": "string", "example": "0.00" }, "currency": { "description": "The Document Currency the invoice was recorded in (ADR 0160).", "type": "string", "example": "VES", "enum": [ "USD", "VES" ] }, "registration_date": { "description": "The day the Company booked the invoice (ADR 0157).", "type": "string", "format": "date", "example": "2023-01-05" }, "functional_currency": { "description": "The Company's functional currency, as frozen on this invoice.", "type": "string", "example": "VES" }, "reporting_currency": { "description": "The Company's reporting currency, as frozen on this invoice.", "type": "string", "example": "USD" }, "functional_total": { "type": "string", "example": "1160.00" }, "reporting_total": { "type": "string", "example": "1160.00" }, "functional_balance": { "type": "string", "example": "1160.00" }, "reporting_balance": { "type": "string", "example": "1160.00" }, "rate_snapshot": { "description": "The rates the invoice is valued with. Both legs are the identity rate until approval freezes a published one, so a draft reads the same amount in all three books.", "properties": { "currency": { "type": "string", "example": "VES" }, "functional_rate": { "type": "string", "example": "1.00000000" }, "functional_rate_reference": { "type": "string", "format": "uuid", "nullable": true }, "reporting_rate": { "type": "string", "example": "1.00000000" }, "reporting_rate_reference": { "type": "string", "format": "uuid", "nullable": true }, "rate_rule": { "type": "string", "example": "identity", "enum": [ "identity", "value_date", "opening" ] }, "rate_value_date": { "type": "string", "format": "date", "example": "2023-01-05" }, "rate_known_at": { "type": "string", "format": "date-time", "nullable": true }, "rate_origin": { "type": "string", "example": "official", "nullable": true } }, "type": "object" }, "observations": { "type": "string", "nullable": true }, "purchase_order_id": { "description": "The Purchase Order this invoice was created from («Facturar orden»); null otherwise. While set, the invoice is in USD (ADR 0326).", "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000", "nullable": true }, "provider_invoice_number": { "description": "The provider's own invoice number (Captured Fiscal Identity).", "type": "string", "example": "00012345", "nullable": true }, "without_fiscal_credit": { "type": "boolean" }, "no_fiscal_credit_reason": { "type": "string", "nullable": true }, "no_fiscal_credit_note": { "type": "string", "nullable": true }, "control_number": { "description": "The fiscal control number transcribed from the provider's document.", "type": "string", "example": "00-99887766", "nullable": true }, "responsible_user_id": { "description": "Optional company user id for the Purchases Invoice Responsable", "type": "string", "nullable": true }, "provider_fiscal_snapshot": { "description": "Provider fiscal identity frozen at approval (MER-2881). Null until the invoice is approved under this slice.", "properties": { "document_type": { "type": "string", "nullable": true, "enum": [ "rif", "cedula", "passport" ] }, "document_number": { "type": "string", "nullable": true }, "legal_name": { "type": "string", "nullable": true }, "vat_taxpayer_type": { "type": "string", "nullable": true }, "special_taxpayer_since": { "type": "string", "format": "date", "nullable": true }, "islr_person_type": { "type": "string", "nullable": true } }, "type": "object", "nullable": true }, "items": { "type": "array", "items": { "required": [ "item_name" ], "properties": { "id": { "type": "string" }, "category_id": { "type": "string" }, "item_id": { "type": "string" }, "item_name": { "description": "The name of the line's catalog item (MER-3674); null when the item is out of the company's reach. Always present.", "type": "string", "example": "Servicio (ficticio)", "nullable": true }, "quantity": { "type": "string", "example": "1.00" }, "unit_id": { "type": "string" }, "unit_price": { "type": "string", "example": "1000.00" }, "subtotal": { "type": "string", "example": "1000.00" }, "tax_id": { "type": "string" }, "tax_percentage": { "type": "string", "example": "16.00" }, "tax_kind": { "type": "string", "example": "vat_general", "enum": [ "vat_general", "vat_reduced", "vat_additional", "exempt", "exonerated", "not_subject", "export", "other" ] }, "discount_percentage": { "type": "string", "example": "0.00" }, "accounting_center_id": { "type": "string" }, "accounting_account_id": { "type": "string" }, "purchase_order_item_id": { "description": "The purchase order line the invoice line draws from; null when none.", "type": "string", "nullable": true }, "purchase_order_unit_price": { "description": "MER-5304: the unit price of the purchase order line it bills, in the order's currency; null for a line of no order line. A line bills another price when unit_price × (100 − discount_percentage) differs from this × (100 − purchase_order_discount_percentage).", "type": "string", "example": "2.00", "nullable": true }, "purchase_order_discount_percentage": { "description": "MER-5304: the discount percentage of the purchase order line it bills; null for a line of no order line.", "type": "string", "example": "0.00", "nullable": true }, "islr_classification": { "description": "The ISLR Concept code the line pays, or not_subject; null when the line is unclassified.", "type": "string", "example": "professional_fees", "nullable": true }, "islr_classification_reason": { "description": "Why the line departs from its item's default ISLR classification; null when it does not.", "type": "string", "example": "Reembolso de gastos de viaje", "nullable": true }, "price_difference_reason": { "description": "MER-5304 (ADR 0346): why the line bills its purchase order line at another price: discount, price_adjustment or error; null for a line at the order's price or of no order line.", "type": "string", "example": "price_adjustment", "nullable": true, "enum": [ "discount", "price_adjustment", "error" ] }, "po_matched_quantity": { "description": "Frozen at approval (ADR 0346): the units of its order line, in the order line's unit, that receipts brought before the invoice and that its price difference applies to; null for a draft or a line that matched none at another price.", "type": "string", "example": "10.0000", "nullable": true }, "po_price_difference_original": { "description": "Frozen at approval: the price difference on those units in the invoice's currency, signed as cost (positive raises the goods' cost, negative lowers it); null when po_matched_quantity is.", "type": "string", "example": "1.00", "nullable": true }, "po_price_difference_functional": { "description": "Frozen at approval: the same difference in the functional book, beyond any exchange difference, signed as cost.", "type": "string", "example": "44.00", "nullable": true }, "po_price_difference_reporting": { "description": "Frozen at approval: the same difference in the reporting book, signed as cost.", "type": "string", "example": "1.00", "nullable": true }, "po_received_quantity": { "description": "Frozen at approval (MER-5525, ADR 0349): the units its order line had received, in the order line's unit; null for a draft, a line approved before MER-5525, or a line whose receipts close nothing on In-Transit.", "type": "string", "example": "0.0000", "nullable": true }, "po_unmatched_quantity": { "description": "Frozen at approval (MER-5525, ADR 0349): the line's units no receipt had matched, which it left on In-Transit at its dollars; a receipt of its order line after it takes part of its price into the stock, and the invoice is then cancelled only with its order. Null when po_received_quantity is.", "type": "string", "example": "10.0000", "nullable": true } }, "type": "object" } }, "tax_summaries": { "description": "Per-tax snapshots materialized on approve; empty until the invoice is approved.", "type": "array", "items": { "properties": { "tax_id": { "type": "string", "format": "uuid" }, "tax_kind": { "type": "string", "example": "vat_general", "enum": [ "vat_general", "vat_reduced", "vat_additional", "exempt", "exonerated", "not_subject", "export", "other" ] }, "tax_percentage": { "type": "string", "example": "16.00" }, "taxable_base": { "type": "string", "example": "1000.00" }, "tax_amount": { "type": "string", "example": "160.00" }, "functional_base": { "description": "The base in the Company's functional currency. Null on a summary written before MER-2878.", "type": "string", "example": "1000.00", "nullable": true }, "functional_tax": { "type": "string", "example": "160.00", "nullable": true }, "reporting_base": { "type": "string", "example": "1000.00", "nullable": true }, "reporting_tax": { "type": "string", "example": "160.00", "nullable": true } }, "type": "object" } }, "capture_discrepancy": { "description": "Present when Captured Amounts sit outside the ADR 0126 bound for the live official rate. Null when in-bound or when captures/rate are unavailable.", "properties": { "in_bound": { "type": "boolean", "example": false }, "fingerprint": { "description": "SHA-256 of the current OOB assessment; required by POST capture-discrepancy/accept.", "type": "string", "pattern": "^[a-f0-9]{64}$", "example": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "maxLength": 64, "minLength": 64 }, "groups": { "type": "array", "items": { "properties": { "tax_id": { "type": "string", "format": "uuid" }, "tax_percentage": { "type": "string", "example": "16.00" }, "rate": { "type": "string", "example": "130.00000000", "nullable": true }, "source_line_count": { "type": "integer", "example": 1 }, "in_bound": { "type": "boolean", "example": false }, "expected": { "properties": { "base": { "type": "string", "example": "13000.00" }, "tax": { "type": "string", "example": "2080.00" }, "total": { "type": "string", "example": "15080.00" } }, "type": "object" }, "captured": { "properties": { "base": { "type": "string", "example": "13050.00", "nullable": true }, "tax": { "type": "string", "example": "2080.00", "nullable": true }, "total": { "type": "string", "example": "15130.00", "nullable": true } }, "type": "object" } }, "type": "object" } } }, "type": "object", "nullable": true }, "capture_discrepancy_accepted": { "description": "Accepted Capture Discrepancy mark (MER-2885). Null when none is registered or after captures change.", "properties": { "accepted_at": { "type": "string", "example": "2026-09-24 16:00:00" }, "accepted_by": { "type": "string", "example": "123e4567-e89b-12d3-a456-426614174000" }, "reason": { "type": "string", "example": "Proveedor redondeó el IVA en el físico", "maxLength": 500 }, "fingerprint": { "description": "Fingerprint of the OOB assessment that was accepted; approve bypass requires it to still match.", "type": "string", "pattern": "^[a-f0-9]{64}$", "example": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "maxLength": 64, "minLength": 64 } }, "type": "object", "nullable": true }, "has_live_notes": { "description": "Whether any Supplier Credit or Debit Note of the invoice is not cancelled, drafts included, whatever note permissions the caller holds: what blocks its cancellation (MER-3292).", "type": "boolean", "example": true }, "is_credited": { "description": "«Con nota de crédito», derived and never stored: at least one Supplier Credit Note of the invoice is approved (with_supplier_credit or applied), whatever note permissions the caller holds. Unlike the sales «Acreditada», it does not depend on the balance.", "type": "boolean", "example": true }, "notes": { "description": "Every Supplier Credit and Debit Note of the invoice, cancelled ones included, by emission date, then code, then id; only the kinds the caller may view: credit notes with backoffice.purchases.credit-notes.view, debit notes with backoffice.purchases.debit-notes.view. [] when there are none or the caller may view neither kind; never a 403.", "type": "array", "items": { "$ref": "#/components/schemas/PurchasesInvoiceNote" } } }, "type": "object" } } } }, "404": { "description": "Purchases invoice not found; a supplier note's id answers it too" }, "403": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Backoffice - Purchases Invoices" ], "summary": "Update a purchases invoice", "operationId": "5bef9dd35046a7ca8382b59bc10fd29e", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "code", "provider_id", "payment_term", "emission_date", "accounting_center_id", "accounting_account_payable_id", "items" ], "properties": { "code": { "type": "string", "example": "INV-001" }, "provider_id": { "type": "string", "format": "uuid" }, "payment_term": { "description": "When the provider is owed payment: cash, or 5, 7, 15 or 30 days after emission_date. Any other value answers 422 with errors.payment_term.", "type": "string", "example": "cash", "enum": [ "cash", "five_days", "seven_days", "fifteen_days", "thirty_days" ] }, "emission_date": { "type": "string", "format": "date" }, "currency": { "description": "The Document Currency. Omit it to keep the one stored. Only USD and VES are published (ADR 0120); any other three-letter code answers 422 with purchases_invoice_currency_not_supported. An invoice of a purchase order stays in USD, sent or kept; any other answers 422 purchases_invoice_purchase_order_currency_mismatch (ADR 0326). Editable only while the invoice is to_be_approved.", "type": "string", "example": "VES", "nullable": true, "maxLength": 3, "minLength": 3 }, "registration_date": { "description": "The day the Company books the invoice (ADR 0157). Omit it to keep the one stored, which follows the emission date if that date has overtaken it. It must satisfy emission_date <= registration_date <= today in the Company's timezone; outside that window the response is 422 with purchases_invoice_registration_date_out_of_range.", "type": "string", "format": "date", "example": "2023-01-05", "nullable": true }, "provider_invoice_number": { "description": "The provider's own invoice number. Omit both fiscal fields to keep the stored Captured Fiscal Identity. Malformed values answer 422 with invalid_provider_invoice_number.", "type": "string", "example": "00012345", "nullable": true }, "control_number": { "description": "The fiscal control number. Omit both fiscal fields to keep the stored Captured Fiscal Identity. Malformed values answer 422 with invalid_control_number.", "type": "string", "example": "00-99887766", "nullable": true }, "captured_amounts": { "description": "Per-tax-group amounts transcribed from the provider's fiscal document in statutory-books currency (MER-2884). Omit to keep the stored Captured Amounts. Pass null or [] to clear.", "type": "array", "items": { "required": [ "tax_id", "tax_percentage", "base", "tax" ], "properties": { "tax_id": { "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000" }, "tax_percentage": { "type": "string", "pattern": "^(?:0*(?:[0-9]|[1-9][0-9])(?:\\.[0-9]{1,2})?|0*100(?:\\.0{1,2})?)$", "example": "16.00" }, "base": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,2})?$", "example": "13000.00" }, "tax": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,2})?$", "example": "2080.00" } }, "type": "object" }, "nullable": true }, "accounting_center_id": { "type": "string", "format": "uuid" }, "accounting_account_payable_id": { "type": "string", "format": "uuid" }, "location_id": { "type": "string", "format": "uuid", "nullable": true }, "reference": { "type": "string", "nullable": true }, "observations": { "type": "string", "nullable": true }, "items": { "type": "array", "items": { "required": [ "id", "category_id", "item_id", "quantity", "unit_id", "unit_price", "tax_id", "tax_percentage", "discount_percentage", "accounting_center_id", "accounting_account_id" ], "properties": { "id": { "description": "The id of a stored line to keep it, or a new id for a line added in the edit. A kept line keeps the purchase order line it bills; a new one bills none, so an invoice of a purchase order refuses it (422 purchases_invoice_purchase_order_line_missing). A purchase_order_item_id in the body is ignored (MER-4961).", "type": "string", "format": "uuid" }, "category_id": { "type": "string", "format": "uuid" }, "item_id": { "type": "string", "format": "uuid" }, "quantity": { "description": "Number or decimal string with at most four fractional digits, at least 0.01.", "oneOf": [ { "type": "number", "example": 1.25, "minimum": 0.01 }, { "type": "string", "pattern": "^(?!0+(?:\\.0{1,4})?$)\\d+(?:\\.\\d{1,4})?$", "example": "1.25" } ] }, "unit_id": { "type": "string", "format": "uuid" }, "unit_price": { "description": "Number or decimal string with at most two fractional digits, at least 0.", "oneOf": [ { "type": "number", "example": 10.1, "minimum": 0 }, { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,2})?$", "example": "10.10" } ] }, "tax_id": { "type": "string", "format": "uuid" }, "tax_percentage": { "description": "Number or decimal string with at most two fractional digits, from 0 to 100.", "oneOf": [ { "type": "number", "example": 16, "maximum": 100, "minimum": 0 }, { "type": "string", "pattern": "^(?:0*(?:[0-9]|[1-9][0-9])(?:\\.[0-9]{1,2})?|0*100(?:\\.0{1,2})?)$", "example": "16.00" } ] }, "discount_percentage": { "description": "Number or decimal string with at most two fractional digits, from 0 to 100.", "oneOf": [ { "type": "number", "example": 10, "maximum": 100, "minimum": 0 }, { "type": "string", "pattern": "^(?:0*(?:[0-9]|[1-9][0-9])(?:\\.[0-9]{1,2})?|0*100(?:\\.0{1,2})?)$", "example": "10.00" } ] }, "accounting_center_id": { "type": "string", "format": "uuid" }, "accounting_account_id": { "type": "string", "format": "uuid" }, "islr_classification": { "description": "An ISLR Concept code of the company's country catalog, or not_subject. Omitted or null: the stored classification of the line with this id when its item is unchanged, otherwise the item's default ISLR classification. A code no catalog row carries answers 422 unknown_islr_classification; a malformed value answers 422 with errors.", "type": "string", "pattern": "^[a-z][a-z0-9_]{0,63}$", "example": "not_subject", "nullable": true, "maxLength": 64 }, "islr_classification_reason": { "description": "Why the line departs from its item's default ISLR classification: 1 to 255 characters once trimmed, otherwise 422 with errors. Required when islr_classification differs from the item's default (422 islr_classification_reason_required); ignored otherwise.", "type": "string", "example": "Reembolso de gastos de viaje", "nullable": true }, "price_difference_reason": { "description": "MER-5304 (ADR 0346): why a line of an invoice of a purchase order bills its order line at another price net of its discount (unit_price × (100 − discount_percentage) / 100 compared exactly with the order line's): discount, price_adjustment or error. Required on such a line (422 purchases_invoice_line_price_difference_reason_required, its message under errors.items.{n}.price_difference_reason); a reason on a line at the order's price is cleared, and it is ignored on a line of no order line.", "type": "string", "example": "price_adjustment", "nullable": true, "enum": [ "discount", "price_adjustment", "error" ] } }, "type": "object" } }, "preview": { "description": "Optional scale-2 preview. String amounts only. Null or omitted skips the comparison.", "required": [ "subtotal", "discount", "taxes", "total", "tax_groups" ], "properties": { "subtotal": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,2})?$", "example": "12.63" }, "discount": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,2})?$", "example": "1.26" }, "taxes": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,2})?$", "example": "1.82" }, "total": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,2})?$", "example": "13.19" }, "tax_groups": { "type": "array", "items": { "required": [ "tax_id", "tax_percentage", "base", "tax" ], "properties": { "tax_id": { "type": "string", "format": "uuid" }, "tax_percentage": { "type": "string", "pattern": "^(?:0*(?:[0-9]|[1-9][0-9])(?:\\.[0-9]{1,2})?|0*100(?:\\.0{1,2})?)$", "example": "16.00" }, "base": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,2})?$", "example": "11.36" }, "tax": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,2})?$", "example": "1.82" } }, "type": "object" } } }, "type": "object", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Purchases invoice updated successfully", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Duplicate code, a modification the invoice lifecycle forbids, purchases_invoice_preview_mismatch, purchases_invoice_tax_selection_invalid, or, on an invoice of a purchase order, an order rule the edit cannot satisfy (MER-4961): the order no longer takes invoices because it is fully invoiced or cancelled (purchase_order_cannot_be_invoiced), or the quantity the lines bill of an order line, added up, exceeds what is still pending of it (invoice_quantity_exceeds_available). Pending counts only approved invoices, so the draft never counts against itself." }, "422": { "description": "A value the client can correct: a reference the company cannot bind (unknown, inactive, owned by another company, or provider fiscal identity incomplete), an unpublished currency, a registration date outside its window, invalid fiscal identity or captured amounts, an ISLR line classification the company's catalog does not know or that departs from its item's default without a reason, an inventoriable PO-linked line that does not use the Inventory In-Transit account (purchase_invoice_inventoriable_line_requires_in_transit_account) or a missing in-transit configuration for such a line (purchase_invoice_inventory_in_transit_account_missing), an inventoriable line with no purchase order line behind it posted to one of the company's inventory accounts, the asset accounts of its items or the Inventory In-Transit account (purchase_invoice_inventory_account_without_receipt, MER-5277, with its message under errors.items.{n}.accounting_account_id), the invoice is linked to a purchase order and its currency (sent or kept) is not USD (purchases_invoice_purchase_order_currency_mismatch, ADR 0326, which also carries invoice_code, purchase_order_id, purchase_order_currency and invoice_currency), the invoice is linked to a purchase order and a line bills no line of it, such as a line added in the edit (purchases_invoice_purchase_order_line_missing, MER-4961, which also carries invoice_code, purchase_order_id and line_ids), a line of an invoice of a purchase order whose product or unit differs from the order line it bills (purchases_invoice_line_does_not_match_purchase_order_line, MER-4961, which also carries invoice_line_id, purchase_order_id, purchase_order_item_id, expected_item_id and expected_unit_id), a line of an invoice of a purchase order at another price than its order line without a reason (purchases_invoice_line_price_difference_reason_required, MER-5304, with its message under errors.items.{n}.price_difference_reason and invoice_line_id, purchase_order_item_id, purchase_order_unit_price and purchase_order_discount_percentage), request validation, or a computed total above 9999999999999.99 (purchases_invoice_total_exceeds_storage). Reference, currency and registration-date refusals carry error with violations or field; overflow and the other refusals use the standard title/status/detail/error_code/errors envelope.", "content": { "application/json": { "schema": { "oneOf": [ { "required": [ "error", "detail" ], "properties": { "error": { "type": "string", "example": "purchases_invoice_references_not_bindable", "enum": [ "purchases_invoice_references_not_bindable", "purchases_invoice_currency_not_supported", "purchases_invoice_registration_date_out_of_range" ] }, "detail": { "type": "string", "example": "La factura no puede vincular estas referencias: Artículo: 123e4567-e89b-12d3-a456-426614174000 (inactivo)." }, "field": { "description": "The request field to put the message on. Absent for purchases_invoice_references_not_bindable.", "type": "string", "example": "currency", "enum": [ "currency", "registration_date" ] }, "violations": { "type": "array", "items": { "properties": { "reference_kind": { "type": "string", "example": "item" }, "reference_id": { "type": "string", "example": "123e4567-e89b-12d3-a456-426614174000" }, "reason": { "type": "string", "example": "INACTIVE", "enum": [ "NOT_FOUND", "INACTIVE", "FISCAL_IDENTITY_INCOMPLETE" ] }, "human_message": { "type": "string", "example": "Artículo: el registro está inactivo." }, "missing": { "description": "Present for FISCAL_IDENTITY_INCOMPLETE", "type": "array", "items": { "type": "string" } } }, "type": "object" } } }, "type": "object" }, { "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422, "enum": [ 422 ] }, "detail": { "type": "string", "example": "El total <19999999999999.98> de la factura de compra supera el límite de almacenamiento 9999999999999.99." }, "error_code": { "description": "Domain refusal code, including purchases_invoice_total_exceeds_storage, invalid_purchases_invoice_payment_term, invalid_provider_invoice_number, invalid_control_number, captured-amount errors, the ISLR line classification refusals unknown_islr_classification, islr_classification_reason_required, invalid_islr_classification_reason, the PO inventoriable-line transit refusals purchase_invoice_inventoriable_line_requires_in_transit_account and purchase_invoice_inventory_in_transit_account_missing, the free inventoriable-line inventory-account refusal purchase_invoice_inventory_account_without_receipt, purchases_invoice_purchase_order_currency_mismatch, purchases_invoice_purchase_order_line_missing, purchases_invoice_line_does_not_match_purchase_order_line and purchases_invoice_line_price_difference_reason_required; null for request validation.", "type": "string", "example": "purchases_invoice_total_exceeds_storage", "nullable": true }, "errors": { "description": "Request field errors for validation; for a domain refusal that names line fields (purchase_invoice_inventory_account_without_receipt under items.{n}.accounting_account_id, purchases_invoice_line_price_difference_reason_required under items.{n}.price_difference_reason), its messages keyed by those fields; null for the other domain refusals.", "type": "object", "example": null, "nullable": true } }, "type": "object" } ] } } } }, "409": { "description": "The provider invoice number is already registered on another non-cancelled document of the same provider within the invoices' kind group", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "detail": { "type": "string", "example": "El número de factura del proveedor ya está registrado en la factura de compra FAC-00001" }, "error_code": { "type": "string", "example": "purchases_invoice_provider_number_already_registered" }, "existing_code": { "description": "The code of the document that holds the number; empty when it cannot be named.", "type": "string", "example": "FAC-00001" }, "existing_kind": { "description": "The kind of that document; null exactly when existing_code is empty.", "type": "string", "example": "regular", "nullable": true, "enum": [ "regular", "opening", "credit_note", "debit_note" ] }, "errors": { "type": "object", "example": null, "nullable": true } }, "type": "object" } } } }, "403": { "description": "Unauthorized" }, "404": { "description": "Purchases invoice not found, or the purchase order it bills is not found (purchase_order_not_found)" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/purchases-invoices/import": { "post": { "tags": [ "Backoffice - Purchases Invoices" ], "summary": "Import purchases invoices from Excel file", "description": "Imports purchases invoices with items from Excel file with denormalized structure", "operationId": "3f125093ebe3cba5de7a0db2c3fc7131", "parameters": [ { "name": "tenant", "in": "path", "description": "Company tenant ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "properties": { "file": { "description": "Excel file with purchases invoices", "type": "string", "format": "binary" } }, "type": "object" } } } }, "responses": { "202": { "description": "Import started successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean" }, "import_id": { "type": "string", "format": "uuid" }, "message": { "type": "string" } }, "type": "object" } } } }, "403": { "description": "Unauthorized - User does not have permission to import invoices" }, "422": { "description": "Validation error - Invalid file format or missing file" }, "500": { "description": "Internal server error" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/purchases-invoices/import/{importId}/status": { "get": { "tags": [ "Backoffice - Purchases Invoices" ], "summary": "Get import status", "description": "Returns the current status of a purchases invoice import job", "operationId": "004a1095ccf684cb0af5c461c993c2ce", "parameters": [ { "name": "tenant", "in": "path", "description": "Company tenant ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "importId", "in": "path", "description": "Import job ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Import status retrieved successfully", "content": { "application/json": { "schema": { "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed" ] }, "progress": { "type": "integer" }, "imported_count": { "type": "integer" }, "skipped_count": { "type": "integer" }, "items_imported_count": { "type": "integer" }, "total_count": { "type": "integer" }, "errors": { "type": "array", "items": { "type": "string" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "original_filename": { "type": "string" }, "started_at": { "type": "string", "format": "date-time", "nullable": true }, "completed_at": { "type": "string", "format": "date-time", "nullable": true } }, "type": "object" } } } }, "404": { "description": "Import job not found or belongs to another company" }, "403": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/purchases-invoices": { "get": { "tags": [ "Backoffice - Purchases Invoices" ], "summary": "Search purchases invoices", "operationId": "e09e3a2b2e6558178b45d947650a351e", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "provider_id", "in": "query", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "kind", "in": "query", "description": "Filter by invoice kind: regular or opening. Omit to return both.", "schema": { "type": "string", "enum": [ "regular", "opening" ] } }, { "name": "kinds[]", "in": "query", "description": "The payable kinds to list (MER-3291), read from the query string only. Omitted, only the invoices proper (regular and opening) are listed. debit_note also needs backoffice.purchases.debit-notes.view, the view permission the shared supplier note kind map names (MER-3292), otherwise 403; a credit_note or any other kind answers 422. The payment form sends regular, opening and debit_note, the kinds a payment settles. A debit note row has the invoice row's shape with kind debit_note.", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "regular", "opening", "debit_note" ] }, "minItems": 1 } }, { "name": "code", "in": "query", "schema": { "type": "string" } }, { "name": "emission_date_from", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "emission_date_to", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "sort_by", "in": "query", "schema": { "type": "string" } }, { "name": "sort_order", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "page", "in": "query", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "List of purchases invoices", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "properties": { "id": { "type": "string" }, "kind": { "description": "A debit note row has the invoice row's shape with kind `debit_note`; `hasAccountingConfigurationGaps` is always false on it (MER-3499).", "type": "string", "example": "regular", "enum": [ "regular", "opening", "debit_note" ] }, "hasAccountingConfigurationGaps": { "type": "boolean" } }, "type": "object" } }, "meta": { "properties": { "total": { "type": "integer" }, "per_page": { "type": "integer" }, "current_page": { "type": "integer" } }, "type": "object" } }, "type": "object" } } } }, "403": { "description": "Unauthorized" }, "422": { "description": "Invalid query filters (for example kind outside regular|opening, or a kinds[] outside regular|opening|debit_note)" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Purchases Invoices" ], "summary": "Create a new purchases invoice", "operationId": "b4f16756bae2f7663960df2ecb08dec6", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "id", "code", "provider_id", "payment_term", "emission_date", "accounting_center_id", "accounting_account_payable_id", "items" ], "properties": { "id": { "description": "Client-supplied invoice identifier. It is the only identifier the client can predict, and the one to read the invoice back with.", "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000" }, "code": { "type": "string", "example": "INV-001", "maxLength": 50 }, "provider_id": { "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000" }, "payment_term": { "description": "When the provider is owed payment: cash, or 5, 7, 15 or 30 days after emission_date. Any other value answers 422 with errors.payment_term.", "type": "string", "example": "cash", "enum": [ "cash", "five_days", "seven_days", "fifteen_days", "thirty_days" ] }, "emission_date": { "description": "Deliberately narrowed to YYYY-MM-DD. The validator rule is date and accepts looser inputs; the stored and returned value is a calendar date.", "type": "string", "format": "date", "example": "2023-01-01" }, "currency": { "description": "The Document Currency the provider billed in. Omit it to take the Company's functional currency, or USD when purchase_order_id is set (ADR 0326); with purchase_order_id, any other currency answers 422 purchases_invoice_purchase_order_currency_mismatch. Only USD and VES are published (ADR 0120); any other three-letter code answers 422 with purchases_invoice_currency_not_supported, because it is a rejected value rather than a malformed request.", "type": "string", "example": "VES", "nullable": true, "maxLength": 3, "minLength": 3 }, "registration_date": { "description": "The day the Company books the invoice (ADR 0157). Omit it to register on the emission date. It must satisfy emission_date <= registration_date <= today in the Company's timezone; outside that window the response is 422 with purchases_invoice_registration_date_out_of_range.", "type": "string", "format": "date", "example": "2023-01-05", "nullable": true }, "provider_invoice_number": { "description": "The provider's own invoice number (Captured Fiscal Identity). Kept as printed (ADR 0380): trimmed, then 1 to 30 letters, digits, spaces, hyphens, ° or º, with case and inner spaces kept. Malformed values answer 422 with invalid_provider_invoice_number.", "type": "string", "example": "00012345", "nullable": true }, "control_number": { "description": "The fiscal control number transcribed from the provider's document. Kept as printed like provider_invoice_number; malformed values answer 422 with invalid_control_number.", "type": "string", "example": "00-99887766", "nullable": true }, "captured_amounts": { "description": "Per-tax-group amounts transcribed from the provider's fiscal document in statutory-books currency (MER-2884). Required at approve when Document Currency differs from statutory books under a Company Fiscal Profile. Omit or null to leave empty.", "type": "array", "items": { "required": [ "tax_id", "tax_percentage", "base", "tax" ], "properties": { "tax_id": { "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000" }, "tax_percentage": { "type": "string", "pattern": "^(?:0*(?:[0-9]|[1-9][0-9])(?:\\.[0-9]{1,2})?|0*100(?:\\.0{1,2})?)$", "example": "16.00" }, "base": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,2})?$", "example": "13000.00" }, "tax": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,2})?$", "example": "2080.00" } }, "type": "object" }, "nullable": true }, "accounting_center_id": { "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000" }, "accounting_account_payable_id": { "description": "An Accounting Account identifier. Resolve it with accounting/payable-accounts/lookup, whose id is the underlying account.", "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000" }, "location_id": { "description": "Resolve it with inventory/locations/lookup.", "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000", "nullable": true }, "reference": { "type": "string", "example": "REF-001", "nullable": true, "maxLength": 100 }, "observations": { "type": "string", "example": "Some observations", "nullable": true }, "purchase_order_id": { "description": "The Purchase Order this invoice bills («Facturar orden»). The invoice is issued in the order's currency at its prices: omit currency to take USD (ADR 0326); with purchase_order_id, any other currency answers 422 purchases_invoice_purchase_order_currency_mismatch.", "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000", "nullable": true }, "responsible_user_id": { "description": "Optional company user id for the Purchases Invoice Responsable", "type": "string", "nullable": true }, "items": { "description": "Line identifiers are assigned by the server. A supplied items[].id is ignored, so the invoice id is the only identifier a client can read back.", "type": "array", "items": { "required": [ "category_id", "item_id", "quantity", "unit_id", "unit_price", "tax_id", "tax_percentage", "discount_percentage", "accounting_center_id", "accounting_account_id" ], "properties": { "category_id": { "description": "Must equal the item's category_id, as returned by inventory/items/lookup.", "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000" }, "item_id": { "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000" }, "quantity": { "description": "Number or decimal string with at most four fractional digits, at least 0.01.", "oneOf": [ { "type": "number", "example": 1.25, "minimum": 0.01 }, { "type": "string", "pattern": "^(?!0+(?:\\.0{1,4})?$)\\d+(?:\\.\\d{1,4})?$", "example": "1.25" } ] }, "unit_id": { "description": "Must be one of the item's unit_ids, as returned by inventory/items/lookup.", "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000" }, "unit_price": { "description": "Number or decimal string with at most two fractional digits, at least 0.", "oneOf": [ { "type": "number", "example": 10.1, "minimum": 0 }, { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,2})?$", "example": "10.10" } ] }, "tax_id": { "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000" }, "tax_percentage": { "description": "Number or decimal string with at most two fractional digits, from 0 to 100.", "oneOf": [ { "type": "number", "example": 16, "maximum": 100, "minimum": 0 }, { "type": "string", "pattern": "^(?:0*(?:[0-9]|[1-9][0-9])(?:\\.[0-9]{1,2})?|0*100(?:\\.0{1,2})?)$", "example": "16.00" } ] }, "discount_percentage": { "description": "Number or decimal string with at most two fractional digits, from 0 to 100.", "oneOf": [ { "type": "number", "example": 10, "maximum": 100, "minimum": 0 }, { "type": "string", "pattern": "^(?:0*(?:[0-9]|[1-9][0-9])(?:\\.[0-9]{1,2})?|0*100(?:\\.0{1,2})?)$", "example": "10.00" } ] }, "accounting_center_id": { "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000" }, "accounting_account_id": { "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000" }, "purchase_order_item_id": { "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000", "nullable": true }, "islr_classification": { "description": "An ISLR Concept code of the company's country catalog, or not_subject. Omitted or null: the item's default ISLR classification. A code no catalog row carries answers 422 unknown_islr_classification; a malformed value answers 422 with errors.", "type": "string", "pattern": "^[a-z][a-z0-9_]{0,63}$", "example": "not_subject", "nullable": true, "maxLength": 64 }, "islr_classification_reason": { "description": "Why the line departs from its item's default ISLR classification: 1 to 255 characters once trimmed, otherwise 422 with errors. Required when islr_classification differs from the item's default (422 islr_classification_reason_required); ignored otherwise.", "type": "string", "example": "Reembolso de gastos de viaje", "nullable": true }, "price_difference_reason": { "description": "MER-5304 (ADR 0346): why a line of an invoice of a purchase order bills its order line at another price net of its discount (unit_price × (100 − discount_percentage) / 100 compared exactly with the order line's): discount, price_adjustment or error. Required on such a line (422 purchases_invoice_line_price_difference_reason_required, its message under errors.items.{n}.price_difference_reason); a reason on a line at the order's price is cleared, and it is ignored on a line of no order line.", "type": "string", "example": "price_adjustment", "nullable": true, "enum": [ "discount", "price_adjustment", "error" ] } }, "type": "object" }, "minItems": 1 }, "preview": { "description": "Optional scale-2 preview. String amounts only. Null or omitted skips the comparison.", "required": [ "subtotal", "discount", "taxes", "total", "tax_groups" ], "properties": { "subtotal": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,2})?$", "example": "12.63" }, "discount": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,2})?$", "example": "1.26" }, "taxes": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,2})?$", "example": "1.82" }, "total": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,2})?$", "example": "13.19" }, "tax_groups": { "type": "array", "items": { "required": [ "tax_id", "tax_percentage", "base", "tax" ], "properties": { "tax_id": { "type": "string", "format": "uuid" }, "tax_percentage": { "type": "string", "pattern": "^(?:0*(?:[0-9]|[1-9][0-9])(?:\\.[0-9]{1,2})?|0*100(?:\\.0{1,2})?)$", "example": "16.00" }, "base": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,2})?$", "example": "11.36" }, "tax": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,2})?$", "example": "1.82" } }, "type": "object" } } }, "type": "object", "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Purchases invoice created successfully. The body is an empty JSON object and carries no identifier; read the invoice with GET /api/backoffice/{tenant}/purchases/purchases-invoices/{id} using the client-supplied id.", "content": { "application/json": { "schema": { "type": "object" } } } }, "200": { "description": "Replay: the id already holds an invoice created with this same content (line ids aside, lines in any order, decimals by value, an omitted currency or registration_date read as the default it took, ISLR classifications compared as resolved so an omitted one reads as the item's current default). Nothing is written and no event is recorded; the invoice is answered as it stands, approved or cancelled since included. The body is the same empty JSON object as the 201.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Duplicate code, purchases_invoice_preview_mismatch, purchases_invoice_tax_selection_invalid, or an order/quantity rule the invoice cannot satisfy", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Bad Request" }, "status": { "type": "integer", "example": 400 }, "detail": { "type": "string", "example": "The given data was invalid." }, "error_code": { "type": "string", "example": "duplicate_purchases_invoice_code", "nullable": true }, "errors": { "type": "object", "example": { "code": [ "The code field is required." ] }, "nullable": true } }, "type": "object" } } } }, "422": { "description": "A value the client can correct: a reference the company cannot bind (unknown, inactive, owned by another company, or provider fiscal identity incomplete), an unpublished currency, a registration date outside its window, invalid fiscal identity or captured amounts, an ISLR line classification the company's catalog does not know or that departs from its item's default without a reason, an inventoriable PO-linked line that does not use the Inventory In-Transit account (purchase_invoice_inventoriable_line_requires_in_transit_account) or a missing in-transit configuration for such a line (purchase_invoice_inventory_in_transit_account_missing), an inventoriable line with no purchase order line behind it posted to one of the company's inventory accounts, the asset accounts of its items or the Inventory In-Transit account (purchase_invoice_inventory_account_without_receipt, MER-5277, with its message under errors.items.{n}.accounting_account_id), a currency other than USD on an invoice of a purchase order (purchases_invoice_purchase_order_currency_mismatch, which also carries invoice_code, purchase_order_id, purchase_order_currency and invoice_currency), a line of an invoice of a purchase order that bills no line of it (purchases_invoice_purchase_order_line_missing, MER-4961, which also carries invoice_code, purchase_order_id and line_ids; a backstop, since a line without purchase_order_item_id answers 400 invoice_quantity_exceeds_available first), a line whose product or unit differs from the order line it bills (purchases_invoice_line_does_not_match_purchase_order_line, MER-4961, which also carries invoice_line_id, purchase_order_id, purchase_order_item_id, expected_item_id and expected_unit_id), a line at another price than its order line without a reason (purchases_invoice_line_price_difference_reason_required, MER-5304, with its message under errors.items.{n}.price_difference_reason and invoice_line_id, purchase_order_item_id, purchase_order_unit_price and purchase_order_discount_percentage), request validation, or a computed total above 9999999999999.99 (purchases_invoice_total_exceeds_storage). Reference, currency and registration-date refusals carry error with violations or field; overflow and the other refusals use the standard title/status/detail/error_code/errors envelope.", "content": { "application/json": { "schema": { "oneOf": [ { "required": [ "error", "detail" ], "properties": { "error": { "type": "string", "example": "purchases_invoice_references_not_bindable", "enum": [ "purchases_invoice_references_not_bindable", "purchases_invoice_currency_not_supported", "purchases_invoice_registration_date_out_of_range" ] }, "detail": { "type": "string", "example": "La factura no puede vincular estas referencias: Artículo: 123e4567-e89b-12d3-a456-426614174000 (inactivo)." }, "field": { "description": "The request field to put the message on. Absent for purchases_invoice_references_not_bindable.", "type": "string", "example": "currency", "enum": [ "currency", "registration_date" ] }, "violations": { "type": "array", "items": { "properties": { "reference_kind": { "type": "string", "example": "item" }, "reference_id": { "type": "string", "example": "123e4567-e89b-12d3-a456-426614174000" }, "reason": { "type": "string", "example": "INACTIVE", "enum": [ "NOT_FOUND", "INACTIVE", "FISCAL_IDENTITY_INCOMPLETE" ] }, "human_message": { "type": "string", "example": "Artículo: el registro está inactivo." }, "missing": { "description": "Present for FISCAL_IDENTITY_INCOMPLETE", "type": "array", "items": { "type": "string" } } }, "type": "object" } } }, "type": "object" }, { "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422, "enum": [ 422 ] }, "detail": { "type": "string", "example": "El total <19999999999999.98> de la factura de compra supera el límite de almacenamiento 9999999999999.99." }, "error_code": { "description": "Domain refusal code, including purchases_invoice_total_exceeds_storage, invalid_purchases_invoice_payment_term, invalid_provider_invoice_number, invalid_control_number, captured-amount errors, the ISLR line classification refusals unknown_islr_classification, islr_classification_reason_required, invalid_islr_classification_reason, the PO inventoriable-line transit refusals purchase_invoice_inventoriable_line_requires_in_transit_account and purchase_invoice_inventory_in_transit_account_missing, the free inventoriable-line inventory-account refusal purchase_invoice_inventory_account_without_receipt, purchases_invoice_purchase_order_currency_mismatch, purchases_invoice_purchase_order_line_missing, purchases_invoice_line_does_not_match_purchase_order_line and purchases_invoice_line_price_difference_reason_required; null for request validation.", "type": "string", "example": "purchases_invoice_total_exceeds_storage", "nullable": true }, "errors": { "description": "Request field errors for validation; for a domain refusal that names line fields (purchase_invoice_inventory_account_without_receipt under items.{n}.accounting_account_id, purchases_invoice_line_price_difference_reason_required under items.{n}.price_difference_reason), its messages keyed by those fields; null for the other domain refusals.", "type": "object", "example": null, "nullable": true } }, "type": "object" } ] } } } }, "409": { "description": "purchases_invoice_id_conflict: the id is already used for other content, or by another document; or purchases_invoice_provider_number_already_registered: the provider invoice number is already registered on another non-cancelled document of the same provider within the invoices' kind group, which also carries existing_code and existing_kind", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "detail": { "type": "string", "example": "El número de factura del proveedor ya está registrado en la factura de compra FAC-00001" }, "error_code": { "type": "string", "example": "purchases_invoice_provider_number_already_registered", "enum": [ "purchases_invoice_id_conflict", "purchases_invoice_provider_number_already_registered" ] }, "existing_code": { "description": "Only on purchases_invoice_provider_number_already_registered: the code of the document that holds the number; empty when it cannot be named.", "type": "string", "example": "FAC-00001" }, "existing_kind": { "description": "Only on purchases_invoice_provider_number_already_registered: the kind of that document; null exactly when existing_code is empty.", "type": "string", "example": "regular", "nullable": true, "enum": [ "regular", "opening", "credit_note", "debit_note" ] }, "errors": { "type": "object", "example": null, "nullable": true } }, "type": "object" } } } }, "403": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/purchases-invoices/{id}/responsible": { "put": { "tags": [ "Backoffice - Purchases Invoices" ], "summary": "Reassign the responsible user of a purchases invoice", "operationId": "f7ce1e86f0945f71c6d5c76de0d35f46", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "responsible_user_id" ], "properties": { "responsible_user_id": { "description": "Company user id that becomes the Purchases Invoice Responsable; null clears it", "type": "string", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Responsible reassigned" }, "403": { "description": "Forbidden" }, "404": { "description": "Purchases invoice not found" }, "409": { "description": "Responsible cannot be reassigned in the current status" }, "422": { "description": "Validation error" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/purchases-invoices/template-import": { "get": { "tags": [ "Backoffice - Purchases Invoices" ], "summary": "Download purchases invoices import template", "description": "Downloads an Excel template file for importing purchases invoices with denormalized structure (header + items per row)", "operationId": "2c00bcc5228b062897d91cc4049cda6a", "parameters": [ { "name": "tenant", "in": "path", "description": "Company tenant ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Excel template file downloaded successfully", "headers": { "Cache-Control": { "description": "Always no-store: the workbook is never cached", "schema": { "type": "string", "example": "no-store, private" } } }, "content": { "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": {} } }, "403": { "description": "Problem JSON, title Forbidden. Without backoffice.purchases.purchases-invoices.view the route can: middleware answers with error_code and errors null; the tenant middleware stack (API-key guardrails, company access, tenant membership) answers without error_code, with a reason only from tenant membership.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ImportTemplateProblem" }, { "$ref": "#/components/schemas/ImportTemplateMiddlewareForbidden" } ] } } } }, "500": { "description": "Unexpected failure, reported. Problem JSON with error_code and errors null; the detail is generic in production.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportTemplateProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/purchases/purchases-invoices/export": { "get": { "tags": [ "Backoffice - Purchases Invoices" ], "summary": "Export facturas de compra to XLSX", "description": "Exports all matching documents up to 5000 rows, ignoring pagination. Nonempty ids[] is an exclusive selection of at most 500 submitted UUIDs: every other filter is ignored, including invalid stale filters. Company isolation always applies. Filtered invoices default to regular/opening; a supplier note kind is exported only when kind or kinds[] names it, and only for a caller holding that kind's own view permission (MER-3292). A selection exports regular and opening documents and the supplier notes of the kinds the caller may view; a selected note of another kind is left out, as another company's document is. Every filter is read from the query string only. Columns A-P keep their existing positions. Q (Afecta a) contains the same-company regular/opening origin invoice code for supplier credit/debit notes, or is blank for invoices and missing or invalid origins. R (Con nota de crédito) is Sí/No for regular/opening invoices: Sí means at least one same-company credit note is approved (with_supplier_credit or applied). R is blank for notes. Both appended columns are literal text.", "operationId": "789cb8a55c0999551f3a4729695f3bee", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "ids[]", "in": "query", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 500 } }, { "name": "status", "in": "query", "style": "form", "explode": true, "schema": { "type": "string", "enum": [ "to_be_approved", "to_be_paid", "fully_paid", "partially_paid", "cancelled", "with_supplier_credit", "applied", "all" ] } }, { "name": "status[]", "in": "query", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "to_be_approved", "to_be_paid", "fully_paid", "partially_paid", "cancelled", "with_supplier_credit", "applied" ] } } }, { "name": "provider_id", "in": "query", "style": "form", "explode": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "provider_id[]", "in": "query", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" } } }, { "name": "responsible_user_id", "in": "query", "style": "form", "explode": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "responsible_user_id[]", "in": "query", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "label_ids[]", "in": "query", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 20 } }, { "name": "sort_order", "in": "query", "style": "form", "explode": true, "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "purchase_contract_id", "in": "query", "style": "form", "explode": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "kind", "in": "query", "description": "credit_note also needs backoffice.purchases.credit-notes.view and debit_note backoffice.purchases.debit-notes.view, otherwise 403. Legacy single-kind form of kinds[]: sending both answers 422.", "style": "form", "explode": true, "schema": { "type": "string", "enum": [ "regular", "opening", "credit_note", "debit_note" ] } }, { "name": "kinds[]", "in": "query", "description": "The document kinds to export, as on the list (MER-3292). Omitted, with no kind, only regular and opening documents. A note kind needs its own view permission, otherwise 403; an unknown kind answers 422.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "regular", "opening", "credit_note", "debit_note" ] }, "minItems": 1 } }, { "name": "code", "in": "query", "style": "form", "explode": true, "schema": { "type": "string" } }, { "name": "name", "in": "query", "style": "form", "explode": true, "schema": { "type": "string" } }, { "name": "emission_date_from", "in": "query", "style": "form", "explode": true, "schema": { "type": "string", "format": "date" } }, { "name": "emission_date_to", "in": "query", "style": "form", "explode": true, "schema": { "type": "string", "format": "date" } }, { "name": "auto_approved", "in": "query", "style": "form", "explode": true, "schema": { "type": "string", "enum": [ "1", "0", "true", "false" ] } }, { "name": "auto_approved_from", "in": "query", "style": "form", "explode": true, "schema": { "type": "string", "format": "date" } }, { "name": "auto_approved_to", "in": "query", "style": "form", "explode": true, "schema": { "type": "string", "format": "date" } }, { "name": "sort_by", "in": "query", "style": "form", "explode": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "XLSX attachment; an empty match returns a header-only sheet.", "headers": { "Cache-Control": { "description": "Always no-store: the workbook is never cached", "schema": { "type": "string", "example": "no-store, private" } } }, "content": { "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "format": "binary" } } } }, "403": { "description": "Missing backoffice.purchases.purchases-invoices.view (the route answers title Forbidden), or a kind naming a supplier note kind whose own view permission the caller lacks (title Unauthorized). Both carry status 403, error_code null and errors null." }, "422": { "description": "Invalid active-mode query (an unknown kind or status, or kind with kinds[]), more than 500 selected IDs or more than 5000 matching documents" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/clients/lookup": { "get": { "tags": [ "Backoffice - Sales - Client Lookups" ], "summary": "Lookup Clients for tenant forms", "operationId": "0802e81a719441d6107e32f2f320d7f5", "parameters": [ { "name": "search", "in": "query", "schema": { "type": "string", "maxLength": 255 } }, { "name": "id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "active", "inactive" ] } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 200, "minimum": 1 } } ], "responses": { "200": { "description": "Minimal Client projection", "content": { "application/json": { "schema": { "properties": { "items": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "default_payment_term": { "type": "string", "nullable": true, "enum": [ "cash", "five_days", "seven_days", "fifteen_days", "thirty_days" ] }, "name": { "type": "string" }, "code": { "type": "string" }, "default_price_list_id": { "type": "string", "format": "uuid", "nullable": true }, "fiscal_identity": { "properties": { "document_number": { "type": "string", "nullable": true }, "is_final_consumer": { "type": "boolean" }, "complete": { "type": "boolean" }, "missing": { "type": "array", "items": { "type": "string" } } }, "type": "object" } }, "type": "object" } }, "total": { "type": "integer" }, "per_page": { "type": "integer" }, "current_page": { "type": "integer" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Not a member of this tenant" }, "404": { "description": "Tenant not found" }, "422": { "description": "Invalid status filter" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/clients/{clientId}/comments": { "get": { "tags": [ "Backoffice - Sales - Clients" ], "summary": "Get client comments", "description": "VIEW permission for comments and attachments; author or administrator deletion rules. UPDATE permission for label assignments. Company catalog management requires its separate permission.", "operationId": "f88f208cbb5787ad9f1d6346f43c8c9b", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "clientId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Scoped collection", "content": { "application/json": { "schema": { "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ClientComment" } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientMiddlewareMessage" } } } }, "403": { "description": "Insufficient permission or ownership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ClientProblem" }, { "$ref": "#/components/schemas/ClientMiddlewareForbidden" }, { "$ref": "#/components/schemas/ClientMiddlewareMessage" } ] } } } }, "404": { "description": "Missing or foreign document", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ClientProblem" }, { "$ref": "#/components/schemas/ClientMiddlewareMessage" } ] } } } }, "422": { "description": "Field validation or typed fiscal validation", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ClientValidationProblem" }, { "$ref": "#/components/schemas/ClientProblem" }, { "$ref": "#/components/schemas/ClientRequestValidation" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Sales - Clients" ], "summary": "Post client comments", "description": "VIEW permission for comments and attachments; author or administrator deletion rules. UPDATE permission for label assignments. Company catalog management requires its separate permission.", "operationId": "04ceb8bcd8268cc620395b8dc7cebf7a", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "clientId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "id", "body" ], "properties": { "parent_id": { "description": "Same-document comment; replies resolve to its root.", "type": "string", "format": "uuid", "nullable": true }, "id": { "description": "UUIDv7", "type": "string", "format": "uuid" }, "body": { "type": "string", "maxLength": 5000, "minLength": 1 } }, "type": "object" } } } }, "responses": { "201": { "description": "Success; null body" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientMiddlewareMessage" } } } }, "403": { "description": "Insufficient permission or ownership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ClientProblem" }, { "$ref": "#/components/schemas/ClientMiddlewareForbidden" }, { "$ref": "#/components/schemas/ClientMiddlewareMessage" } ] } } } }, "404": { "description": "Missing or foreign document", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ClientProblem" }, { "$ref": "#/components/schemas/ClientMiddlewareMessage" } ] } } } }, "422": { "description": "Field validation or typed fiscal validation", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ClientValidationProblem" }, { "$ref": "#/components/schemas/ClientProblem" }, { "$ref": "#/components/schemas/ClientRequestValidation" } ] } } } }, "409": { "description": "Conflicting creation or idempotency payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/clients/{clientId}/comments/{commentId}": { "put": { "tags": [ "Backoffice - Sales - Clients" ], "summary": "Put client comments/{commentId}", "description": "VIEW permission for comments and attachments; author or administrator deletion rules. UPDATE permission for label assignments. Company catalog management requires its separate permission.", "operationId": "d7376f771f2a83489b96716ad71afd77", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "clientId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "commentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "body" ], "properties": { "body": { "type": "string", "maxLength": 5000, "minLength": 1 } }, "type": "object" } } } }, "responses": { "200": { "description": "Success; null body" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientMiddlewareMessage" } } } }, "403": { "description": "Insufficient permission or ownership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ClientProblem" }, { "$ref": "#/components/schemas/ClientMiddlewareForbidden" }, { "$ref": "#/components/schemas/ClientMiddlewareMessage" } ] } } } }, "404": { "description": "Missing or foreign document", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ClientProblem" }, { "$ref": "#/components/schemas/ClientMiddlewareMessage" } ] } } } }, "422": { "description": "Field validation or typed fiscal validation", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ClientValidationProblem" }, { "$ref": "#/components/schemas/ClientProblem" }, { "$ref": "#/components/schemas/ClientRequestValidation" } ] } } } }, "409": { "description": "Conflicting creation or idempotency payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Backoffice - Sales - Clients" ], "summary": "Delete client comments/{commentId}", "description": "VIEW permission for comments and attachments; author or administrator deletion rules. UPDATE permission for label assignments. Company catalog management requires its separate permission.", "operationId": "dce6e27cdf5ff25a855d88913deed0f1", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "clientId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "commentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientMiddlewareMessage" } } } }, "403": { "description": "Insufficient permission or ownership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ClientProblem" }, { "$ref": "#/components/schemas/ClientMiddlewareForbidden" }, { "$ref": "#/components/schemas/ClientMiddlewareMessage" } ] } } } }, "404": { "description": "Missing or foreign document", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ClientProblem" }, { "$ref": "#/components/schemas/ClientMiddlewareMessage" } ] } } } }, "422": { "description": "Field validation or typed fiscal validation", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ClientValidationProblem" }, { "$ref": "#/components/schemas/ClientProblem" }, { "$ref": "#/components/schemas/ClientRequestValidation" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/clients/{clientId}/attachments": { "get": { "tags": [ "Backoffice - Sales - Clients" ], "summary": "Get client attachments", "description": "VIEW permission for comments and attachments; author or administrator deletion rules. UPDATE permission for label assignments. Company catalog management requires its separate permission.", "operationId": "f8541d1a6011fbe5250213fd0e1bc142", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "clientId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Scoped collection", "content": { "application/json": { "schema": { "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ClientAttachment" } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientMiddlewareMessage" } } } }, "403": { "description": "Insufficient permission or ownership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ClientProblem" }, { "$ref": "#/components/schemas/ClientMiddlewareForbidden" }, { "$ref": "#/components/schemas/ClientMiddlewareMessage" } ] } } } }, "404": { "description": "Missing or foreign document", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ClientProblem" }, { "$ref": "#/components/schemas/ClientMiddlewareMessage" } ] } } } }, "422": { "description": "Field validation or typed fiscal validation", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ClientValidationProblem" }, { "$ref": "#/components/schemas/ClientProblem" }, { "$ref": "#/components/schemas/ClientRequestValidation" } ] } } } }, "503": { "description": "Attachment storage unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachmentStorageUnavailableProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Sales - Clients" ], "summary": "Post client attachments", "description": "VIEW permission for comments and attachments; author or administrator deletion rules. UPDATE permission for label assignments. Company catalog management requires its separate permission.", "operationId": "2ee5662423e269ac2bac51a1f4351e22", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "clientId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "id", "file" ], "properties": { "id": { "description": "UUIDv7", "type": "string", "format": "uuid" }, "file": { "description": "PDF JPG JPEG PNG WebP XLSX CSV DOCX; extension and MIME verified; maximum 15 MiB", "type": "string", "format": "binary" }, "comment_id": { "type": "string", "format": "uuid", "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Success; null body" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientMiddlewareMessage" } } } }, "403": { "description": "Insufficient permission or ownership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ClientProblem" }, { "$ref": "#/components/schemas/ClientMiddlewareForbidden" }, { "$ref": "#/components/schemas/ClientMiddlewareMessage" } ] } } } }, "404": { "description": "Missing or foreign document", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ClientProblem" }, { "$ref": "#/components/schemas/ClientMiddlewareMessage" } ] } } } }, "422": { "description": "Field validation or typed fiscal validation", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ClientValidationProblem" }, { "$ref": "#/components/schemas/ClientProblem" }, { "$ref": "#/components/schemas/ClientRequestValidation" } ] } } } }, "409": { "description": "Conflicting creation or idempotency payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientProblem" } } } }, "503": { "description": "Attachment storage unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachmentStorageUnavailableProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/clients/{clientId}/attachments/{attachmentId}/download": { "get": { "tags": [ "Backoffice - Sales - Clients" ], "summary": "Get client attachments/{attachmentId}/download", "description": "VIEW permission for comments and attachments; author or administrator deletion rules. UPDATE permission for label assignments. Company catalog management requires its separate permission.", "operationId": "ea8876d1efc8123b489ec308ef869b1e", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "clientId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "attachmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Temporary private download", "content": { "application/json": { "schema": { "required": [ "url", "expires_at" ], "properties": { "url": { "type": "string", "format": "uri" }, "expires_at": { "type": "string", "format": "date-time" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientMiddlewareMessage" } } } }, "403": { "description": "Insufficient permission or ownership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ClientProblem" }, { "$ref": "#/components/schemas/ClientMiddlewareForbidden" }, { "$ref": "#/components/schemas/ClientMiddlewareMessage" } ] } } } }, "404": { "description": "Missing or foreign document", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ClientProblem" }, { "$ref": "#/components/schemas/ClientMiddlewareMessage" } ] } } } }, "422": { "description": "Field validation or typed fiscal validation", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ClientValidationProblem" }, { "$ref": "#/components/schemas/ClientProblem" }, { "$ref": "#/components/schemas/ClientRequestValidation" } ] } } } }, "503": { "description": "Attachment storage unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachmentStorageUnavailableProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/clients/{clientId}/attachments/{attachmentId}": { "delete": { "tags": [ "Backoffice - Sales - Clients" ], "summary": "Delete client attachments/{attachmentId}", "description": "VIEW permission for comments and attachments; author or administrator deletion rules. UPDATE permission for label assignments. Company catalog management requires its separate permission.", "operationId": "01a321a72fc4c6998785c6a12dd098e0", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "clientId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "attachmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientMiddlewareMessage" } } } }, "403": { "description": "Insufficient permission or ownership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ClientProblem" }, { "$ref": "#/components/schemas/ClientMiddlewareForbidden" }, { "$ref": "#/components/schemas/ClientMiddlewareMessage" } ] } } } }, "404": { "description": "Missing or foreign document", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ClientProblem" }, { "$ref": "#/components/schemas/ClientMiddlewareMessage" } ] } } } }, "422": { "description": "Field validation or typed fiscal validation", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ClientValidationProblem" }, { "$ref": "#/components/schemas/ClientProblem" }, { "$ref": "#/components/schemas/ClientRequestValidation" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/clients/{clientId}/labels/{labelId}": { "put": { "tags": [ "Backoffice - Sales - Clients" ], "summary": "Put client labels/{labelId}", "description": "VIEW permission for comments and attachments; author or administrator deletion rules. UPDATE permission for label assignments. Company catalog management requires its separate permission.", "operationId": "986215faac55a0a90b42e3ad47d6d311", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "clientId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "labelId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientMiddlewareMessage" } } } }, "403": { "description": "Insufficient permission or ownership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ClientProblem" }, { "$ref": "#/components/schemas/ClientMiddlewareForbidden" }, { "$ref": "#/components/schemas/ClientMiddlewareMessage" } ] } } } }, "404": { "description": "Missing or foreign document", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ClientProblem" }, { "$ref": "#/components/schemas/ClientMiddlewareMessage" } ] } } } }, "422": { "description": "Field validation or typed fiscal validation", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ClientValidationProblem" }, { "$ref": "#/components/schemas/ClientProblem" }, { "$ref": "#/components/schemas/ClientRequestValidation" } ] } } } }, "409": { "description": "Conflicting creation or idempotency payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Backoffice - Sales - Clients" ], "summary": "Delete client labels/{labelId}", "description": "VIEW permission for comments and attachments; author or administrator deletion rules. UPDATE permission for label assignments. Company catalog management requires its separate permission.", "operationId": "29cdfef64744840ac621883fbc568818", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "clientId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "labelId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientMiddlewareMessage" } } } }, "403": { "description": "Insufficient permission or ownership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ClientProblem" }, { "$ref": "#/components/schemas/ClientMiddlewareForbidden" }, { "$ref": "#/components/schemas/ClientMiddlewareMessage" } ] } } } }, "404": { "description": "Missing or foreign document", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ClientProblem" }, { "$ref": "#/components/schemas/ClientMiddlewareMessage" } ] } } } }, "422": { "description": "Field validation or typed fiscal validation", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ClientValidationProblem" }, { "$ref": "#/components/schemas/ClientProblem" }, { "$ref": "#/components/schemas/ClientRequestValidation" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/clients/{id}/credit-balances": { "get": { "tags": [ "Backoffice - Sales - Clients" ], "summary": "Read the Customer Credit a client's credit notes keep and its open customer advances", "description": "The client's credit notes that keep Customer Credit, grouped by currency and never summed across currencies (MER-3277), so a collection form can warn before collecting again what a note's credit already covers, and the apply dialog can offer it. The notes are listed only for a caller with backoffice.sales.credit-notes.view; the balance always is. Beside it, under advance_balances, the client's customer advances still applied with a balance, grouped by currency and never summed with the Customer Credit (MER-3279); they are always listed. Each currency group carries reporting_balance, its equivalent in the top-level reporting_currency (MER-3281): the stored reporting-book Carrying Amount summed within that currency, a book value, never a conversion at today's rate. Requires collections.view.", "operationId": "getClientCreditBalances", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The client's Customer Credit and open advances by currency; each list is empty when there is none", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientCreditBalances" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks collections.view" }, "404": { "description": "client_not_found: the client does not exist or belongs to another company (same body for both)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesCreditApplicationProblem" } } } }, "503": { "description": "client_credit_balances_query_failed: the Customer Credit or the open advances could not be read now; retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesCreditApplicationProblem" } } } }, "500": { "description": "client_credit_balances_invalid_data: a stored credit note or advance has a currency or balance that cannot be interpreted; reported", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesCreditApplicationProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/clients/{id}": { "get": { "tags": [ "Backoffice - Sales - Clients" ], "summary": "Find client", "operationId": "1b2467ca5bd2771a422a8043a73f2916", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Client detail; note links retain separate credit-note permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientDetail" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientMiddlewareMessage" } } } }, "403": { "description": "Insufficient permission or ownership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ClientProblem" }, { "$ref": "#/components/schemas/ClientMiddlewareForbidden" }, { "$ref": "#/components/schemas/ClientMiddlewareMessage" } ] } } } }, "404": { "description": "Missing or foreign document", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ClientProblem" }, { "$ref": "#/components/schemas/ClientMiddlewareMessage" } ] } } } }, "422": { "description": "Field validation or typed fiscal validation", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ClientValidationProblem" }, { "$ref": "#/components/schemas/ClientProblem" } ] } } } }, "503": { "description": "client_credit_balances_query_failed: the Customer Credit could not be read now; retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Backoffice - Sales - Clients" ], "summary": "Update client", "operationId": "54f9bec22e1ced4637cff19df59aae1c", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "status" ], "properties": { "default_payment_term": { "type": "string", "nullable": true, "enum": [ "cash", "five_days", "seven_days", "fifteen_days", "thirty_days" ] }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "default_price_list_id": { "type": "string", "format": "uuid", "nullable": true }, "fiscal_identity": { "$ref": "#/components/schemas/ClientFiscalIdentityInput" } }, "type": "object" } } } }, "responses": { "200": { "description": "Success; null body" }, "409": { "description": "Duplicate fiscal document, existing ID, or protected Consumidor final", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ClientDocumentConflict" }, { "$ref": "#/components/schemas/ClientProblem" } ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientMiddlewareMessage" } } } }, "403": { "description": "Insufficient permission or ownership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ClientProblem" }, { "$ref": "#/components/schemas/ClientMiddlewareForbidden" }, { "$ref": "#/components/schemas/ClientMiddlewareMessage" } ] } } } }, "404": { "description": "Missing or foreign document", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ClientProblem" }, { "$ref": "#/components/schemas/ClientMiddlewareMessage" } ] } } } }, "422": { "description": "Field validation or typed fiscal validation", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ClientValidationProblem" }, { "$ref": "#/components/schemas/ClientProblem" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/clients/import": { "post": { "tags": [ "Backoffice - Clients" ], "summary": "Import clients from Excel file", "description": "Imports clients from an Excel file", "operationId": "4ed7ec6fc15ea332865502b5cf236a10", "parameters": [ { "name": "tenant", "in": "path", "description": "Company tenant ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "properties": { "file": { "description": "Excel file with clients", "type": "string", "format": "binary" } }, "type": "object" } } } }, "responses": { "202": { "description": "Import started successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean" }, "import_id": { "type": "string", "format": "uuid" }, "message": { "type": "string" } }, "type": "object" } } } }, "403": { "description": "Unauthorized - User does not have permission to import clients" }, "422": { "description": "Validation error - Invalid file format or missing file" }, "500": { "description": "Internal server error" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/clients/import/{importId}/status": { "get": { "tags": [ "Backoffice - Clients" ], "summary": "Get import status", "description": "Returns the current status of a client import job", "operationId": "e7149a57868d89d9da682dee78fbd338", "parameters": [ { "name": "tenant", "in": "path", "description": "Company tenant ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "importId", "in": "path", "description": "Import job ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Import status retrieved successfully", "content": { "application/json": { "schema": { "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed" ] }, "progress": { "type": "integer" }, "imported_count": { "type": "integer" }, "total_count": { "type": "integer" }, "errors": { "type": "array", "items": { "type": "string" } }, "original_filename": { "type": "string" }, "started_at": { "type": "string", "format": "date-time", "nullable": true }, "completed_at": { "type": "string", "format": "date-time", "nullable": true } }, "type": "object" } } } }, "404": { "description": "Import job not found" }, "403": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/clients": { "get": { "tags": [ "Backoffice - Sales - Clients" ], "summary": "Search clients", "description": "Ungrouped code DESC by default. Status grouping precedes sorting and pagination. Status facets omit only status; label facets omit only labels. Label filter uses OR.", "operationId": "a104cdb3aaf8a7e0a86604fc7d86ecb0", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "search", "in": "query", "schema": { "type": "string" } }, { "name": "name", "in": "query", "schema": { "type": "string" } }, { "name": "code", "in": "query", "schema": { "type": "string" } }, { "name": "description", "in": "query", "schema": { "type": "string" } }, { "name": "document_number", "in": "query", "schema": { "type": "string" } }, { "name": "documentNumber", "in": "query", "schema": { "type": "string" } }, { "name": "email", "in": "query", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "active", "inactive" ] } }, { "name": "status[]", "in": "query", "schema": { "type": "array", "items": { "type": "string", "enum": [ "active", "inactive" ] } } }, { "name": "label_ids[]", "in": "query", "schema": { "type": "array", "items": { "type": "string", "format": "uuid" } } }, { "name": "sort_by", "in": "query", "schema": { "type": "string", "enum": [ "name", "code", "status", "created_at" ] } }, { "name": "sort_order", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "group_by", "in": "query", "schema": { "type": "string", "default": "none", "enum": [ "status", "none" ] } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "Paginated clients with facets", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientListResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientMiddlewareMessage" } } } }, "403": { "description": "Insufficient permission or ownership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ClientProblem" }, { "$ref": "#/components/schemas/ClientMiddlewareForbidden" }, { "$ref": "#/components/schemas/ClientMiddlewareMessage" } ] } } } }, "404": { "description": "Missing or foreign document", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ClientProblem" }, { "$ref": "#/components/schemas/ClientMiddlewareMessage" } ] } } } }, "422": { "description": "Field validation or typed fiscal validation", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ClientValidationProblem" }, { "$ref": "#/components/schemas/ClientProblem" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Sales - Clients" ], "summary": "Create client", "operationId": "4c99d45e25470ed1bd268f0b0a61386a", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "id", "name" ], "properties": { "id": { "type": "string", "format": "uuid" }, "default_payment_term": { "type": "string", "nullable": true, "enum": [ "cash", "five_days", "seven_days", "fifteen_days", "thirty_days" ] }, "name": { "type": "string", "maxLength": 80, "minLength": 3 }, "description": { "type": "string", "nullable": true, "maxLength": 100, "minLength": 3 }, "default_price_list_id": { "type": "string", "format": "uuid", "nullable": true }, "fiscal_identity": { "$ref": "#/components/schemas/ClientFiscalIdentityInput" } }, "type": "object" } } } }, "responses": { "201": { "description": "Success; null body" }, "409": { "description": "Duplicate fiscal document or existing ID", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ClientDocumentConflict" }, { "$ref": "#/components/schemas/ClientProblem" } ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientMiddlewareMessage" } } } }, "403": { "description": "Insufficient permission or ownership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ClientProblem" }, { "$ref": "#/components/schemas/ClientMiddlewareForbidden" }, { "$ref": "#/components/schemas/ClientMiddlewareMessage" } ] } } } }, "404": { "description": "Missing or foreign document", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ClientProblem" }, { "$ref": "#/components/schemas/ClientMiddlewareMessage" } ] } } } }, "422": { "description": "Field validation or typed fiscal validation", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ClientValidationProblem" }, { "$ref": "#/components/schemas/ClientProblem" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/clients/template-import": { "get": { "tags": [ "Backoffice - Clients" ], "summary": "Download clients import template", "description": "Downloads an Excel template file for importing clients", "operationId": "0a4f8d9a093e160fb880ab94930264dc", "parameters": [ { "name": "tenant", "in": "path", "description": "Company tenant ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Excel template file downloaded successfully", "headers": { "Cache-Control": { "description": "Always no-store: the workbook is never cached", "schema": { "type": "string", "example": "no-store, private" } } }, "content": { "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": {} } }, "403": { "description": "Problem JSON, title Forbidden. Without backoffice.sales.clients.view the route can: middleware answers with error_code and errors null; the tenant middleware stack (API-key guardrails, company access, tenant membership) answers without error_code, with a reason only from tenant membership.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ImportTemplateProblem" }, { "$ref": "#/components/schemas/ImportTemplateMiddlewareForbidden" } ] } } } }, "500": { "description": "Unexpected failure, reported. Problem JSON with error_code and errors null; the detail is generic in production.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportTemplateProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/collections/{id}/accounting-readiness": { "get": { "tags": [ "Backoffice - Collections" ], "summary": "Get accounting readiness for a collection", "operationId": "4bd19be1081e6f1d055118466dac3382", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Accounting readiness snapshot", "content": { "application/json": { "schema": { "properties": { "ready": { "type": "boolean" }, "missing": { "type": "array", "items": { "properties": { "reason_code": { "type": "string" }, "subject_type": { "type": "string" }, "subject_id": { "type": "string" }, "human_message": { "type": "string" }, "details": { "type": "array", "items": { "type": "string" } } }, "type": "object" } }, "warnings": { "$ref": "#/components/schemas/AccountingReadinessWarnings" } }, "type": "object" } } } }, "403": { "description": "Unauthorized" }, "404": { "description": "Collection not found" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/collections/{id}/cancel": { "post": { "tags": [ "Backoffice - Sales Collections" ], "summary": "Cancel a collection", "description": "Cancels an applied collection and posts the exact inversion of its entry, linked by reverses_transaction_id and dated the company's today. A customer advance with no live application gives up its whole own balance (its balances read 0.00 and its method lines keep their frozen treasury_relieved) and posts sales_collection.advance_cancelled, the inversion of its sales_collection.advance_received. A credit balance refund (MER-3280) gives each credit note back exactly the Customer Credit it took (never valued again; an emptied note keeps Customer Credit again), marks its credit applications reverted_at, and posts sales_collection.refund_cancelled, the inversion of its sales_collection.refunded, which restores the treasury position. Cancelling a credit note answers 409 sales_credit_note_credit_used_elsewhere while its refund is live. A refund of a customer advance (MER-3641) gives the advance back exactly what it took, never valued again, the same way; cancelling an advance with a live refund answers 409 advance_has_applications until the refund is cancelled.", "operationId": "8c6942c5e840db4efd34b6b202852808", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Collection cancelled successfully" }, "409": { "description": "collection_cannot_be_cancelled: the collection is already cancelled; advance_has_applications: the customer advance relieved a document that has not been unapplied, or a live credit balance refund paid part of it out (MER-3641); or remitted_igtf_requires_adjustment (MER-3690): a standing igtf_perceived withholding remittance paid the IGTF Perceived of one of its method lines to SENIAT, so nothing is reversed or published and its detail names the collection's code; voiding that remittance frees the cancellation, otherwise correct it with a manual entry" }, "403": { "description": "Unauthorized" }, "404": { "description": "Collection not found" }, "500": { "description": "An integrity error, such as a customer advance whose received entry is missing, or a refund whose entry, credit applications, notes or advances cannot be read; nothing is written" }, "422": { "description": "Malformed collection identifier or existing accounting readiness refusal", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CollectionValidationProblem" }, { "required": [ "error", "missing" ], "properties": { "error": { "type": "string", "enum": [ "accounting_configuration_incomplete" ] }, "missing": { "type": "array", "items": { "type": "object", "additionalProperties": true } } }, "type": "object" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/collections/{id}/credit-applications": { "get": { "tags": [ "Backoffice - Sales Collections" ], "summary": "List the credit applications of a customer advance or a credit balance refund", "description": "The credit applications of a collection, live and reverted, by date then the order they were recorded, not paginated. A customer advance (kind advance) lists each application to the client's invoices as applying it answered (MER-3279), and each credit balance refund that paid it out in cash (MER-3641): target {type: collection, id: the refund, code, kind: refund}, never revertible on its own. A credit balance refund (kind refund, «devolución de saldo a favor», MER-3280) lists the credit notes whose customer credit and the customer advances (MER-3641) it paid out: source credit_note or collection with its code, target {type: collection, id: the refund, code, kind: refund}, invoice_relieved holding the official value of the units refunded, and revertible false, since it reverts only by cancelling the refund. A settlement collection lists none. Requires collections.view.", "operationId": "listCollectionCreditApplications", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The collection's credit applications, empty when it has none", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesCreditApplicationList" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks collections.view" }, "404": { "description": "collection_not_found: the collection does not exist or belongs to another company (same body for both)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesCreditApplicationProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/collection-documents/{resource}/{id}": { "get": { "tags": [ "Backoffice - Sales Collections" ], "summary": "A debt as Collections reads it, including settled documents", "operationId": "67a6bbdde7754a63555f4320294b81d7", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "resource", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "sales-invoices", "debit-notes" ] } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Debt identity and settlement facts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionDocument" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Collections view permission required" }, "404": { "description": "Debt not found in this company" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/collection-documents": { "get": { "tags": [ "Backoffice - Sales Collections" ], "summary": "Open customer debts for the Collections form", "operationId": "a5652937189a36a41daecfa9414d6145", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "customer_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "kinds[]", "in": "query", "schema": { "type": "array", "items": { "type": "string", "enum": [ "regular", "opening", "debit_note" ] } } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "Only debt identity and settlement facts", "content": { "application/json": { "schema": { "required": [ "items", "total", "per_page", "current_page" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/CollectionDocument" } }, "total": { "type": "integer" }, "per_page": { "type": "integer" }, "current_page": { "type": "integer" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Collections view permission required" }, "422": { "description": "Invalid query" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/credit-applications/open-invoices": { "get": { "tags": [ "Backoffice - Sales Collections" ], "summary": "Open customer invoices for the credit application action", "operationId": "920a62f47817623e76a60be729bc4f98", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "customer_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "Paginated regular invoice debt facts", "content": { "application/json": { "schema": { "required": [ "items", "total", "per_page", "current_page" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/CollectionDocument" } }, "total": { "type": "integer" }, "per_page": { "type": "integer" }, "current_page": { "type": "integer" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Credit application permission required" }, "422": { "description": "Invalid query" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/collections/{id}": { "get": { "tags": [ "Backoffice - Sales Collections" ], "summary": "Get a collection by ID", "operationId": "8d54ffd13af82eeb6d3547510b410e55", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Collection details", "content": { "application/json": { "schema": { "required": [ "id", "code", "kind", "starter", "date_collection", "date_credited", "customer_id", "customer_name", "customer_code", "created_at", "labels", "amount_collected", "date_collection_applied", "status", "currency", "balance", "functional_balance", "reporting_balance", "collectables", "methods" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "advance_invoice": { "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "status": { "type": "string" } }, "type": "object", "nullable": true }, "can_issue_advance_invoice": { "description": "True only for a live untouched advance without a reserved invoice, whose purpose is not no_service and whose client may receive one.", "type": "boolean" }, "advance_purpose": { "description": "What a customer Advance states it corresponds to when it is registered: service or no_service, with a short text in a person's words (MER-5693, ADR 0373). It never changes. Null for a settlement, a refund and an Advance registered before MER-5693, which reads «Sin indicar».", "required": [ "kind", "detail" ], "properties": { "kind": { "type": "string", "enum": [ "service", "no_service" ] }, "detail": { "type": "string", "maxLength": 255 } }, "type": "object", "nullable": true }, "kind": { "description": "A settlement relieves documents; a customer advance (ADR 0214) holds its own balance; a credit balance refund (MER-3280) pays credit notes' Customer Credit out, so its amount_collected left the company and its notes are listed by GET /sales/collections/{id}/credit-applications.", "type": "string", "enum": [ "settlement", "advance", "refund" ] }, "starter": { "required": [ "id", "type" ], "properties": { "id": { "type": "string" }, "type": { "type": "string" } }, "type": "object" }, "date_collection": { "type": "string", "format": "date" }, "date_credited": { "description": "The day the money was credited. Each settlement or advance line's IGTF was classified on it, or on date_collection when absent (MER-3687). It does not change rate selection or the accounting date.", "type": "string", "format": "date", "nullable": true }, "customer_name": { "type": "string", "nullable": true }, "customer_code": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "nullable": true }, "labels": { "type": "array", "items": { "$ref": "#/components/schemas/CollectionLabel" } }, "customer_id": { "type": "string", "format": "uuid" }, "amount_collected": { "type": "string", "example": "1000.00" }, "date_collection_applied": { "type": "string", "format": "date", "nullable": true }, "status": { "type": "string" }, "currency": { "description": "An advance's or a refund's currency; null for a settlement.", "type": "string", "example": "USD", "nullable": true }, "balance": { "description": "What an advance still holds in its currency; 0.00 once cancelled; null for a settlement and a refund.", "type": "string", "example": "500.00", "nullable": true }, "functional_balance": { "description": "The advance balance in the functional book; null for a settlement and a refund.", "type": "string", "example": "65000.00", "nullable": true }, "reporting_balance": { "description": "The advance balance in the reporting book; null for a settlement and a refund.", "type": "string", "example": "500.00", "nullable": true }, "collectables": { "description": "Always empty for an advance and a refund.", "type": "array", "items": { "$ref": "#/components/schemas/CollectionCollectableDetail" } }, "methods": { "description": "The method lines in form order, each with its payment instrument and the Method Line Snapshot it posted to. A label that no longer resolves is an empty string.", "type": "array", "items": { "required": [ "id", "instrument", "amountCollected", "currency", "rate_snapshot", "agreed_rate_pair", "treasury_relieved", "differences", "reference", "treasury_account_id", "treasury_account_name", "accounting_account_id", "accounting_account_code", "accounting_account_name", "perceived_igtf" ], "properties": { "id": { "description": "Stable method line identity", "type": "string", "format": "uuid" }, "instrument": { "required": [ "id", "name", "class" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "example": "Efectivo USD" }, "class": { "description": "Instrument class: cash, bank_transfer, mobile_payment, point_of_sale, zelle, crypto_wallet, check or card.", "type": "string", "example": "cash" } }, "type": "object" }, "amountCollected": { "description": "Units in the instrument currency: the cash received, IGTF included.", "type": "string", "example": "60.00" }, "currency": { "type": "string", "nullable": true }, "agreed_rate_pair": { "$ref": "#/components/schemas/CollectionAgreedSettlementRatePair" }, "rate_snapshot": { "$ref": "#/components/schemas/CollectionRateSnapshot" }, "treasury_relieved": { "$ref": "#/components/schemas/CollectionTreasuryRelieved" }, "differences": { "type": "array", "items": { "$ref": "#/components/schemas/CollectionSettlementDifference" } }, "perceived_igtf": { "$ref": "#/components/schemas/CollectionPerceivedIgtf" }, "reference": { "description": "Free object; migrated lines carry `legacy` with their original text.", "type": "object", "example": { "reference": "TRX-1" }, "additionalProperties": true }, "treasury_account_id": { "description": "Null on a line migrated onto an instrument that stayed unlinked.", "type": "string", "format": "uuid", "nullable": true }, "treasury_account_name": { "type": "string", "example": "Efectivo USD", "nullable": true }, "accounting_account_id": { "type": "string", "format": "uuid" }, "accounting_account_code": { "type": "string", "example": "1.1.01." }, "accounting_account_name": { "type": "string", "example": "Caja" } }, "type": "object" } } }, "type": "object" } } } }, "404": { "description": "Collection not found" }, "403": { "description": "Unauthorized" }, "422": { "description": "Malformed collection identifier", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionValidationProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/collections": { "get": { "tags": [ "Backoffice - Sales Collections" ], "summary": "Search collections with pagination", "operationId": "835d7d4d0f435eca2f8924aa4b54bc51", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 10, "maximum": 100, "minimum": 1 } }, { "name": "status", "in": "query", "description": "One status. To match several, send status[] (MER-3504).", "required": false, "schema": { "type": "string", "enum": [ "applied", "cancelled" ] } }, { "name": "status[]", "in": "query", "description": "Nonempty list; matches a collection in any of the listed statuses (MER-3504).", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "applied", "cancelled" ] }, "minItems": 1 } }, { "name": "kind", "in": "query", "description": "One kind. To match several, send kind[] (MER-3640).", "required": false, "schema": { "type": "string", "enum": [ "settlement", "advance", "refund" ] } }, { "name": "kind[]", "in": "query", "description": "Nonempty list; OR within the field, AND with other filters (MER-3640).", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "settlement", "advance", "refund" ] }, "minItems": 1 } }, { "name": "customer_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "customer_id[]", "in": "query", "description": "Nonempty customer UUID list; OR within this field, AND with other filters.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1 } }, { "name": "search", "in": "query", "schema": { "type": "string" } }, { "name": "date_from", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "date_to", "in": "query", "description": "Inclusive calendar day, on or after date_from.", "schema": { "type": "string", "format": "date" } }, { "name": "label_ids[]", "in": "query", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1 } }, { "name": "sort_by", "in": "query", "schema": { "type": "string", "default": "code", "enum": [ "date_collection", "code", "amount_collected", "created_at" ] } }, { "name": "sort_order", "in": "query", "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } }, { "name": "code", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "invoice_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Collections list", "content": { "application/json": { "schema": { "required": [ "items", "total", "per_page", "current_page", "meta" ], "properties": { "items": { "type": "array", "items": { "required": [ "id", "code", "kind", "starter", "date_collection", "date_credited", "customer_id", "customer_name", "customer_code", "created_at", "invoices", "labels", "amount_collected", "date_collection_applied", "status", "currency", "balance", "functional_balance", "reporting_balance", "hasAccountingConfigurationGaps" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "starter": { "required": [ "id", "type" ], "properties": { "id": { "type": "string" }, "type": { "type": "string" } }, "type": "object" }, "date_collection_applied": { "type": "string", "format": "date", "nullable": true }, "hasAccountingConfigurationGaps": { "type": "boolean" }, "customer_name": { "type": "string", "nullable": true }, "customer_code": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "nullable": true }, "invoices": { "type": "array", "items": { "$ref": "#/components/schemas/CollectionInvoiceDisplay" } }, "labels": { "type": "array", "items": { "$ref": "#/components/schemas/CollectionLabel" } }, "kind": { "description": "refund: a credit balance refund (MER-3280), money paid out.", "type": "string", "enum": [ "settlement", "advance", "refund" ] }, "date_collection": { "type": "string", "format": "date" }, "date_credited": { "description": "Informational crediting date; does not change rate selection or accounting date.", "type": "string", "format": "date", "nullable": true }, "customer_id": { "type": "string", "format": "uuid" }, "amount_collected": { "type": "string", "example": "1000.00" }, "status": { "type": "string" }, "currency": { "description": "An advance's or a refund's currency; null for a settlement.", "type": "string", "nullable": true }, "balance": { "description": "What an advance still holds; null for a settlement and a refund.", "type": "string", "nullable": true }, "functional_balance": { "description": "The advance balance in the functional book; null for a settlement.", "type": "string", "nullable": true }, "reporting_balance": { "description": "The advance balance in the reporting book; null for a settlement.", "type": "string", "nullable": true } }, "type": "object" } }, "total": { "type": "integer" }, "per_page": { "type": "integer" }, "current_page": { "type": "integer" }, "meta": { "required": [ "counts", "kind_counts", "label_counts" ], "properties": { "counts": { "description": "Ignores only status; all other filters remain.", "required": [ "applied", "cancelled" ], "properties": { "applied": { "type": "integer" }, "cancelled": { "type": "integer" } }, "type": "object" }, "kind_counts": { "description": "Ignores only kind; all other filters remain (MER-3640).", "required": [ "settlement", "advance", "refund" ], "properties": { "settlement": { "type": "integer" }, "advance": { "type": "integer" }, "refund": { "type": "integer" } }, "type": "object" }, "label_counts": { "description": "Ignores only label_ids; counts distinct matching collections for active company labels.", "type": "object", "additionalProperties": { "type": "integer" } } }, "type": "object" } }, "type": "object" } } } }, "403": { "description": "Unauthorized" }, "422": { "description": "A filter has the wrong shape, e.g. a list on a single-value filter such as code[], or an unknown value, e.g. kind=nope.", "content": { "application/json": { "schema": { "required": [ "title", "status", "detail", "errors" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string", "example": "The given data was invalid." }, "error_code": { "type": "string", "nullable": true }, "errors": { "description": "Messages per invalid query key, e.g. code or status.0.", "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Sales Collections" ], "summary": "Create a new collection", "description": "A collection is a settlement (kind omitted or settlement), a customer advance (kind=advance, ADR 0214) or a credit balance refund (kind=refund, «devolución de saldo a favor», MER-3280). A refund pays credit notes' Customer Credit and customer Advances (MER-3641) out in cash: money leaves the company. It is registered from its client (starter {id: customer_id, type: client}, the client must belong to the company), settles no document (collectables omitted or empty), carries no agreed_rate, and its method lines are in one currency (else 422 refund_currency_mismatch) and total amount_collected, the money, in that currency; date_collection is Y-m-d, on or after each note's emission and each Advance's collection, and no later than the company's today. credit_applications (1 to 50, required for a refund, prohibited otherwise) names each credit note or customer Advance refunded (MER-3641): a client-owned id that becomes its Credit Application's id, source {type: credit_note, id} or {type: collection, id} and source_units in the source's currency, and the sources share one currency (else 422 refund_currency_mismatch). In the money's currency the units total amount_collected (else 422 refund_credits_total_mismatch). In another, the money and the sources are USD and VES (else 422 refund_currency_mismatch) and the money converts at the official rate of date_collection (MER-5688, ADR 0377): it derives the units exactly, or within the tolerance when every source empties (else 422 derived_debt_does_not_match_applied_amounts, which a rate published since the preview also answers when the money no longer derives the units), and money that derives less than a cent answers 422 refund_amount_below_a_cent. A client takes both figures from the refund preview. A method line on a treasury account that backs a Caja, whatever its kind, needs that Caja's open Turno: it is the first exclusive lock, by ascending Caja id, and a Caja with none answers 409 cash_shift_not_open with its cash_register_id (MER-5688, ADR 0376). An account of no Caja, a bank, a card rail or a safe, needs none. A refund never names its Turno (cash_shift_id is prohibited), and cancelling one needs none. Then the notes, then the Advances, are locked by ascending id. Each note must be approved and keep Customer Credit of the client (422 application_source_not_open, application_counterparty_mismatch, application_date_precedes_credit_note, sales_credit_note_not_found for a missing note or one of another company); each Advance must be an applied customer Advance of the client collected no later than date_collection (422 application_source_not_open for a settlement or refund collection or a cancelled Advance, application_counterparty_mismatch, application_date_precedes_advance, collection_not_found for a missing collection or one of another company), and an Advance a live advance invoice reserves answers 409 advance_already_invoiced until a total credit note frees it (MER-4264); units beyond what a source holds answer 409 credit_balance_exceeded naming what is available. Each method line reduces its Treasury Position by its proportional Carrying Amount (ADR 0197). The refund is applied on registration and posts sales_collection.refunded: each note's receivable, or each Advance's customer_advances on the account and center its receipt credited, debited at what the source gave up, the cash credited at its Carrying Amount, with debt_currency, rounding and treasury_currency per book. A note emptied turns applied; an Advance emptied stays applied at a zero balance. Replay identity includes the credit applications: the same id with other credits answers 409 collection_id_conflict; an application id already taken answers 409 sales_credit_application_id_conflict. Entry requires collections.create, backoffice.sales.collections.advance or backoffice.sales.collections.refund; a refund then requires backoffice.sales.collections.refund. A collection is a settlement (kind omitted or settlement) or a customer advance (kind=advance, ADR 0214). An advance is registered from its client (starter {id: customer_id, type: client}, the client must belong to the company), settles no document (collectables omitted or empty), counts positive method units in one instrument currency other than USDT, with no agreed_rate, whose settling units (cash less perceived IGTF) total amount_collected; it is applied on registration at the official rate of its cash event (an identity snapshot when the company keeps the currency in both books), holds its own currency and triple balance, and posts sales_collection.advance_received (debit each method account, credit customer_advances). When a USDT line sits next to a line in another currency the USDT refusal answers first (advance_usdt_not_supported). Clients cannot submit currency or own balances (prohibited). Entry requires collections.create or backoffice.sales.collections.advance; a settlement then requires collections.create and an advance backoffice.sales.collections.advance, checked before the body is validated. An advance never consults agree-settlement-rate. A customer Advance states its purpose when it is registered (advance_purpose, required for an advance and prohibited otherwise, MER-5693, ADR 0373): service or no_service, with a short text in a person's words; it never changes, and a wrong one is corrected by cancelling the untouched Advance and registering it again. An Advance Invoice is offered and accepted for an untouched Advance unless its purpose is no_service, which is refused with 422 advance_invoice_no_service. Replay identity includes kind: the same id with the other kind answers 409 collection_id_conflict. A collection is applied on creation. Registration is idempotent by client id: equivalent content returns the stored collection with no repeated effects; different content returns 409 collection_id_conflict. Collectable ids are client-owned and remain stable; method ids are generated once by the server. Each method line goes through an active payment instrument of the company in its own instrument currency (pick one from GET /treasury/payment-instruments/lookup) and freezes the treasury account and accounting account it posts to. Registration freezes one rate snapshot per method currency and settles documents before publishing events. GET detail exposes the frozen settlement. An optional agreed_rate decimal string is captured only with backoffice.sales.collections.agree-settlement-rate, in addition to CREATE. It quotes USD/VES for VES against USD or USD against VES, and USDT/USD or USDT/VES for USDT against that debt; supplying it when the currencies match is invalid. USDT against USD/VES requires it. The actor is derived from the authenticated user and token, never the body. Rates canonicalize to eight decimals and belong to replay identity: omitted and null are equivalent, while a changed, newly added or removed rate conflicts. Equivalent replay returns frozen state without rechecking live rate permission, instruments or official freshness. A new negotiated registration still requires the selected official evidence to be available and fresh. The calculator requires derived debt to match applications. Zero applications are inert; at least one positive application is required. Every positive application names a document of the collection's client (customer_id), else 422 collection_document_of_another_customer. On each positive line a missing document, one of another company or a non-invoice line answers collection_invalid_collectable before that document's client is checked; line order decides only among those identity and client checks. Currency, status and balance are judged after every positive line has passed them (MER-3594). A settlement's starter.id must be among its positive applications' collectableIds (case-insensitive), else 422 collection_starter_not_among_positives before anything is written (MER-4408). From MER-3687, a company with a Fiscal Profile classifies each settlement or advance line's IGTF (art. 4 numeral 6, ADR 0193) on date_credited, or date_collection when omitted. A perceived line's cash splits into base = cash ÷ (1 + rate), rounded half-up, and IGTF = cash − base. Only the base settles debt, so a settlement's applications total what the bases settle and an advance's amount_collected is its cash less its IGTF; a same-currency settlement's amount_collected is likewise its method lines' settling units (cash less perceived IGTF), else 422 collection_methods_total_mismatch (MER-3643), while converting lines keep the derived-debt check; the treasury leg moves the whole cash; the IGTF is credited to igtf_payable. A refund is never classified, on any rail. A line that cannot be classified, and a perceiving line without the igtf_payable role, answer 422 accounting_configuration_incomplete before anything is written; the calculator's rate gaps, derived_debt_does_not_match_applied_amounts and collection_crediting_date_out_of_range answer before them.", "operationId": "b58e713af9641e0f70d070f99ff8d177", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "id", "starter", "date_collection", "customer_id", "amount_collected", "methods" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000" }, "kind": { "description": "Omitted means settlement; refund is a credit balance refund (MER-3280).", "type": "string", "enum": [ "settlement", "advance", "refund" ] }, "starter": { "required": [ "id", "type" ], "properties": { "id": { "description": "A settlement names one of the documents it settles with a positive amount (starter.id among positive collectables' collectableIds, case-insensitive; else 422 collection_starter_not_among_positives, MER-4408); an advance or a refund names its client (customer_id), else 422 advance_starter_customer_mismatch or refund_starter_customer_mismatch.", "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174001" }, "type": { "description": "A settlement starts from an invoice (client gives 422 errors.starter.type); an advance or a refund from its client.", "type": "string", "example": "invoice", "enum": [ "invoice", "client" ] } }, "type": "object" }, "date_collection": { "type": "string", "format": "date", "example": "2023-01-01" }, "date_credited": { "description": "Optional, with date_collection ≤ date_credited ≤ the company's today. Each settlement or advance line's IGTF is classified on it (on date_collection when omitted, MER-3687). It does not change rate selection or the accounting date.", "type": "string", "format": "date", "nullable": true }, "customer_id": { "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174002" }, "advance_purpose": { "description": "Required for an advance, prohibited otherwise (MER-5693, ADR 0373). A customer Advance states its purpose when it is registered: service or no_service, with a short text in a person's words. It never changes; a wrong one is corrected by cancelling the untouched Advance and registering it again. It belongs to replay identity: another purpose under the same id answers 409 collection_id_conflict.", "required": [ "kind", "detail" ], "properties": { "kind": { "type": "string", "example": "no_service", "enum": [ "service", "no_service" ] }, "detail": { "type": "string", "example": "Pago de más sobre la factura 0012", "maxLength": 255, "minLength": 1 } }, "type": "object" }, "amount_collected": { "description": "Number or decimal string, zero or more. For an advance, and for a settlement whose method lines are all in the documents' currency, the lines' settling units (cash less perceived IGTF) total it (422 collection_methods_total_mismatch, MER-3643). Converting settlement lines keep the derived-debt check. For a refund it is the money, in its method lines' currency, which they total, whatever the sources' currency.", "oneOf": [ { "type": "number", "example": 1000.5, "minimum": 0 }, { "type": "string", "pattern": "^\\d+(?:\\.\\d+)?$", "example": "1000.50" } ] }, "collectables": { "description": "A settlement requires at least one line. An advance may omit the field or send an empty array; a line answers 422 errors.collectables.", "type": "array", "items": { "required": [ "id", "collectableId", "type", "amountCollected" ], "properties": { "id": { "type": "string", "format": "uuid" }, "collectableId": { "type": "string", "format": "uuid" }, "type": { "type": "string", "example": "invoice", "enum": [ "invoice" ] }, "amountCollected": { "description": "Application amount in the document currency. Number or decimal string, zero or more, with at most two decimals.", "oneOf": [ { "type": "number", "example": 70, "minimum": 0 }, { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,2})?$", "example": "70.00" } ] } }, "type": "object" } }, "credit_applications": { "description": "Required for a refund, prohibited otherwise: the credit notes whose Customer Credit and the customer Advances (MER-3641) it pays out, each once, sharing one currency. source_units are in that currency, which may differ from the money in amount_collected (MER-5688).", "type": "array", "items": { "required": [ "id", "source", "source_units" ], "properties": { "id": { "description": "Client-owned and stable: the Credit Application's id.", "type": "string", "format": "uuid" }, "source": { "required": [ "type", "id" ], "properties": { "type": { "description": "credit_note for a note's Customer Credit, collection for a customer Advance (MER-3641).", "type": "string", "enum": [ "credit_note", "collection" ] }, "id": { "type": "string", "format": "uuid" } }, "type": "object" }, "source_units": { "description": "In the source's currency, greater than zero, at most two decimals.", "type": "string", "pattern": "^(?!0+(?:\\.0{1,2})?$)\\d{1,13}(?:\\.\\d{1,2})?$", "example": "80.00" } }, "type": "object" }, "maxItems": 50, "minItems": 1 }, "methods": { "description": "The method lines, in form order. Their derived debt must match positive applications (422 derived_debt_does_not_match_applied_amounts).", "type": "array", "items": { "required": [ "instrument_id", "amountCollected" ], "properties": { "instrument_id": { "description": "An active payment instrument of the company in its own instrument currency, whose treasury account is active.", "type": "string", "format": "uuid" }, "amountCollected": { "description": "Instrument-currency units collected: the cash received, IGTF included. Number or decimal string, greater than zero, with at most two decimals.", "oneOf": [ { "type": "number", "example": 60, "exclusiveMinimum": true, "minimum": 0 }, { "type": "string", "pattern": "^(?!0+(?:\\.0{1,2})?$)\\d+(?:\\.\\d{1,2})?$", "example": "60.00" } ] }, "reference": { "description": "Free object. Known keys: `reference` (the transfer or receipt reference) and `notes`; lines migrated from before MER-3102 carry `legacy` with their original text.", "type": "object", "example": { "reference": "TRX-1", "notes": "Pago parcial" }, "additionalProperties": true }, "agreed_rate": { "description": "Optional positive decimal string with 1-12 integer digits and 1-8 decimals. USD/VES quotes VES per USD in either conversion direction; USDT/USD and USDT/VES quote debt currency per USDT. Same-currency input is invalid. Required for USDT against USD/VES. Conditional agree-settlement-rate permission is checked only for a newly captured rate.", "type": "string", "pattern": "^(?!0+\\.0+$)\\d{1,12}\\.\\d{1,8}$", "example": "169.00000000", "nullable": true } }, "type": "object" }, "minItems": 1 }, "cash_shift_id": { "description": "Optional open cash shift of the company to attribute this settlement to (MER-4175). Closed, missing, or other-company shifts answer 422 cash_shift_not_open with no collection row. Prohibited on an advance or a refund; Backoffice cobros may omit it.", "type": "string", "format": "uuid", "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Collection created successfully", "content": { "application/json": { "schema": { "required": [ "id", "code", "status" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string", "example": "COB00042" }, "status": { "type": "string", "enum": [ "applied", "cancelled" ] } }, "type": "object" } } } }, "200": { "description": "Equivalent replay: the stored identity, code and current lifecycle status", "content": { "application/json": { "schema": { "required": [ "id", "code", "status" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string", "example": "COB00042" }, "status": { "type": "string", "enum": [ "applied", "cancelled" ] } }, "type": "object" } } } }, "400": { "description": "sales_invoice_already_fully_collected or collection_exceeds_invoice_balance. Overbalance includes exact document currency and decimal strings.", "content": { "application/json": { "schema": { "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer", "example": 400 }, "detail": { "type": "string" }, "error_code": { "type": "string" }, "errors": { "type": "object", "nullable": true, "additionalProperties": true }, "invoice_code": { "type": "string" }, "invoice_currency": { "type": "string" }, "collection_amount": { "type": "string" }, "available_balance": { "type": "string" }, "invoice_total": { "type": "string" } }, "type": "object" } } } }, "403": { "description": "Without collections.create, backoffice.sales.collections.advance or backoffice.sales.collections.refund; a settlement (or omitted kind) without collections.create; an advance without backoffice.sales.collections.advance; a refund without backoffice.sales.collections.refund; or collection_agreed_settlement_rate_not_permitted for a structurally valid supplied rate without the conditional capability, attributed to methods.N.agreed_rate.", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Forbidden" }, "status": { "type": "integer", "example": 403 }, "detail": { "type": "string" }, "error_code": { "type": "string", "example": "collection_agreed_settlement_rate_not_permitted" }, "errors": { "type": "object", "additionalProperties": true } }, "type": "object" } } } }, "404": { "description": "collection_instrument_not_found: the payment instrument does not exist or belongs to another company (same body for both)." }, "409": { "description": "collection_id_conflict: the collection id is taken by other content, including the same content with another kind or, for a refund, other credit applications; collection_collectable_id_conflict: a client collectable line id is already used; sales_invoice_cannot_be_collected; credit_balance_exceeded: a refund's units exceed what a note or an Advance holds; advance_already_invoiced: a refund names an Advance a live advance invoice reserves (MER-3641); cash_shift_not_open (with cash_register_id): a refund's method line goes through a Caja with no open Turno, or a close won the Turno first (MER-5688); or sales_credit_application_id_conflict: a refund's credit application id is already used", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string" }, "status": { "type": "integer", "example": 409 }, "detail": { "type": "string" }, "error_code": { "type": "string", "enum": [ "collection_id_conflict", "collection_collectable_id_conflict", "sales_invoice_cannot_be_collected", "credit_balance_exceeded", "advance_already_invoiced", "cash_shift_not_open", "sales_credit_application_id_conflict" ] }, "cash_register_id": { "description": "With cash_shift_not_open.", "type": "string", "format": "uuid" } }, "type": "object" } } } }, "422": { "description": "Refund refusals: refund_customer_not_found, refund_starter_customer_mismatch, refund_has_collectables, refund_agreed_rate_not_supported, refund_currency_mismatch (method lines in two currencies, sources in two currencies, or money and sources that differ and are not USD and VES), refund_credits_total_mismatch (in the money's currency, the units do not total amount_collected), derived_debt_does_not_match_applied_amounts (in another currency, the money does not derive the units), refund_amount_below_a_cent (the money derives less than a cent), collection_methods_total_mismatch, sales_credit_note_not_found, collection_not_found, application_source_not_open, application_counterparty_mismatch, application_date_precedes_credit_note, application_date_precedes_advance, unsupported_cash_event_currency, and accounting_configuration_incomplete naming RECEIVABLE_ACCOUNT_MISSING or _INACTIVE (subject invoice, the note), EXCHANGE_POSTING_ACCOUNT_MISSING, OFFICIAL_RATE_STALE or OFFICIAL_RATE_NOT_AVAILABLE, CASH_BANK_ACCOUNT_MISSING or _INACTIVE, LEDGER_FLOW_NOT_PARALLEL_CURRENCY_READY or ACCOUNTING_PERIOD_CLOSED. Settlement refusals: collection_methods_total_mismatch when every method line is in the documents' currency and those lines' settling units (cash less perceived IGTF) do not total amount_collected (MER-3643). Advance refusals: advance_customer_not_found (the client is not the company's), advance_starter_customer_mismatch, advance_has_collectables, advance_usdt_not_supported, advance_agreed_rate_not_supported, advance_single_currency, advance_purpose_invalid, collection_methods_total_mismatch (the method lines' settling units, their cash less any perceived IGTF, do not total amount_collected), and accounting_configuration_incomplete with missing[] naming CUSTOMER_ADVANCES_ACCOUNT_MISSING (subject company), OFFICIAL_RATE_STALE or OFFICIAL_RATE_NOT_AVAILABLE (subject payment_method), CASH_BANK_ACCOUNT_MISSING or _INACTIVE, IGTF_SUBJECT_UNCLASSIFIED or FISCAL_ACCOUNT_MISSING [igtf_payable] as for a settlement, the parallel-flow gap or the closed-period gap. The body is invalid (`errors` names each field, including a prohibited currency, balance, functional_balance or reporting_balance); or `error_code` is collection_instrument_inactive, collection_instrument_treasury_account_inactive or derived_debt_does_not_match_applied_amounts, cash_event_date_in_the_future, collection_crediting_date_out_of_range (date_collection ≤ date_credited ≤ company today), collection_mixes_document_currencies, collection_invalid_collectable (a missing document, one of another company or a non-invoice line) or collection_document_of_another_customer (a positive line names a document of the company whose client is not customer_id; detail names the document code, MER-3594) or collection_starter_not_among_positives (settlement starter.id is not among positive collectables' collectableIds, MER-4408); or `error` is accounting_configuration_incomplete (the existing envelope carries `missing[]`, e.g. OFFICIAL_RATE_STALE, OFFICIAL_RATE_NOT_AVAILABLE or EXCHANGE_POSTING_ACCOUNT_MISSING, plus CASH_BANK_ACCOUNT_INACTIVE on subject_type payment_method with the instrument id; from MER-3687 IGTF_SUBJECT_UNCLASSIFIED on subject_type payment_method with the instrument id and details [cause, igtf_day, methods.N], cause company_tax_attributes_not_configured or rule_not_in_force, and FISCAL_ACCOUNT_MISSING on subject_type company with details [igtf_payable] when a line perceives IGTF; rate gaps, derived_debt_does_not_match_applied_amounts and collection_crediting_date_out_of_range answer first); or collection_agreed_settlement_rate_required: USDT against USD/VES debt requires an agreed rate; or collection_agreed_settlement_rate_converts_nothing: a rate supplied for matching currencies. Both are attributed to methods.N.agreed_rate.", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string", "example": "The method lines total 90.00 but the collected documents total 100.00" }, "error_code": { "type": "string", "example": "derived_debt_does_not_match_applied_amounts" }, "error": { "type": "string", "example": "accounting_configuration_incomplete" }, "missing": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "errors": { "type": "object", "nullable": true, "additionalProperties": true } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/collections/{id}/refund-preview": { "get": { "tags": [ "Backoffice - Sales Collections" ], "summary": "Preview refunding a customer advance in cash", "description": "What a credit balance refund («devolución de saldo a favor», MER-3641) of the customer Advance's balance through one payment instrument on the date would record, by the same eligibility, Rate Snapshot rule, settlement and accounting readiness as registering it (POST /sales/collections with kind refund and credit_applications[].source {type: collection, id}), over the treasury position as it stands, with nothing locked, written or counted: it refuses exactly what registering would. Without source_units it proposes the Advance's whole balance. The instrument must be in the Advance's currency (pick one from GET /treasury/payment-instruments/lookup). source names the Advance and credit_note is absent; source_relieved is what the Advance gives up at its Carrying Amount, official_value the official value of the units paid out, treasury.posted the cash leg at its Carrying Amount (ADR 0197), and differences the Advance leg's debt_currency (leg source) and the cash leg's treasury_currency (leg treasury), signed from the company's side. An Advance a live advance invoice reserves answers 409 advance_already_invoiced until a total credit note frees it (MER-4264). Requires backoffice.sales.collections.refund.", "operationId": "previewCustomerAdvanceRefund", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "The customer Advance: a collection of kind advance.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "instrument_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "date", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "source_units", "in": "query", "description": "Greater than zero, at most two decimals, in the Advance's currency; omitted, the Advance's whole balance. Through an instrument in another currency these are the units asked for: the response's source_units are what its money derives, or the whole balance when it derives that within the tolerance.", "required": false, "schema": { "type": "string", "pattern": "^(?!0+(?:\\.0{1,2})?$)\\d{1,13}(?:\\.\\d{1,2})?$" } } ], "responses": { "200": { "description": "What refunding would record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerCreditRefundPreview" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks backoffice.sales.collections.refund" }, "404": { "description": "collection_not_found: the collection does not exist or belongs to another company; or collection_instrument_not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesCreditApplicationProblem" } } } }, "409": { "description": "advance_already_invoiced: a live advance invoice reserves the Advance (credit it in full first); credit_balance_exceeded: the units exceed the Advance's balance, or it already gave it all up; or cash_shift_not_open (with cash_register_id): the instrument's treasury account backs a Caja with no open Turno (MER-5688)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesCreditApplicationProblem" } } } }, "422": { "description": "The refusals of registering: validation (errors), application_source_not_open (a settlement or refund collection, or a cancelled Advance), refund_currency_mismatch, refund_amount_below_a_cent, application_date_precedes_advance, collection_instrument_inactive, collection_instrument_treasury_account_inactive, cash_event_date_in_the_future, unsupported_cash_event_currency, or the readiness envelope (OFFICIAL_RATE_STALE, OFFICIAL_RATE_NOT_AVAILABLE, CASH_BANK_ACCOUNT_*, EXCHANGE_POSTING_ACCOUNT_MISSING, LEDGER_FLOW_NOT_PARALLEL_CURRENCY_READY, ACCOUNTING_PERIOD_CLOSED).", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/SalesCreditApplicationProblem" }, { "$ref": "#/components/schemas/SalesCreditApplicationAccountingConfigurationError" } ] } } } }, "500": { "description": "An integrity error, such as an Advance whose receipt never posted its customer_advances credit" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/agent-effects/{id}": { "get": { "tags": [ "Backoffice - Sales - Contacts" ], "summary": "Reconcile an immutable effect for the authorized subject", "operationId": "e2eb73919e7ab8142b965587e62509e7", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Contact-Subject", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^\\+[1-9][0-9]{7,14}$" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactProblem" } } } }, "403": { "description": "Insufficient permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactProblem" } } } }, "404": { "description": "Opaque reference or tenant mismatch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactProblem" } } } }, "409": { "description": "Ambiguity, changed effect, contention or version conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactProblem" } } } }, "422": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactProblem" } } } }, "200": { "description": "Successful result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactEffect" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/contacts/{id}": { "get": { "tags": [ "Backoffice - Sales - Contacts" ], "summary": "Read the current authorized contact", "operationId": "c93333d1de08641abf0a2b39bf760671", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Contact-Subject", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^\\+[1-9][0-9]{7,14}$" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactProblem" } } } }, "403": { "description": "Insufficient permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactProblem" } } } }, "404": { "description": "Opaque reference or tenant mismatch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactProblem" } } } }, "409": { "description": "Ambiguity, changed effect, contention or version conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactProblem" } } } }, "422": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactProblem" } } } }, "200": { "description": "Successful result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactView" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "patch": { "tags": [ "Backoffice - Sales - Contacts" ], "summary": "Apply attributed partial contact enrichment", "operationId": "457c5fc13c59df632c39059c4f7f7e21", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Contact-Subject", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^\\+[1-9][0-9]{7,14}$" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactEnrichRequest" } } } }, "responses": { "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactProblem" } } } }, "403": { "description": "Insufficient permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactProblem" } } } }, "404": { "description": "Opaque reference or tenant mismatch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactProblem" } } } }, "409": { "description": "Ambiguity, changed effect, contention or version conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactProblem" } } } }, "422": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactProblem" } } } }, "200": { "description": "Successful result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactEffect" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/contacts/identity": { "post": { "tags": [ "Backoffice - Sales - Contacts" ], "summary": "Resolve exact authorized phone identity", "operationId": "56d741c8b33a1e8f63ffbe0fd937e367", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Contact-Subject", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^\\+[1-9][0-9]{7,14}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactIdentityRequest" } } } }, "responses": { "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactProblem" } } } }, "403": { "description": "Insufficient permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactProblem" } } } }, "404": { "description": "Opaque reference or tenant mismatch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactProblem" } } } }, "409": { "description": "Ambiguity, changed effect, contention or version conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactProblem" } } } }, "422": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactProblem" } } } }, "200": { "description": "Successful result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactIdentityResult" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/contacts": { "post": { "tags": [ "Backoffice - Sales - Contacts" ], "summary": "Capture a sparse contact with an immutable effect", "operationId": "ce825013c961fc4f4fa348af8e545c61", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Contact-Subject", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^\\+[1-9][0-9]{7,14}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactCaptureRequest" } } } }, "responses": { "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactProblem" } } } }, "403": { "description": "Insufficient permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactProblem" } } } }, "404": { "description": "Opaque reference or tenant mismatch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactProblem" } } } }, "409": { "description": "Ambiguity, changed effect, contention or version conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactProblem" } } } }, "422": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactProblem" } } } }, "201": { "description": "Native contact created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactEffect" } } } }, "200": { "description": "Successful result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactEffect" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/contacts/{id}/restriction": { "get": { "tags": [ "Backoffice - Sales - Contacts" ], "summary": "Read contact restriction status (search-friendly NONE when absent)", "operationId": "76da619eef38fe9e68872918f8193bb5", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Contact-Subject", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^\\+[1-9][0-9]{7,14}$" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactProblem" } } } }, "403": { "description": "Insufficient permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactProblem" } } } }, "404": { "description": "Opaque reference or tenant mismatch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactProblem" } } } }, "200": { "description": "Restriction view", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactRestrictionView" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Sales - Contacts" ], "summary": "Register a recoverable contact restriction (baja)", "operationId": "2b9b0136f3e6bcc3a7355f5fde18fa43", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Contact-Subject", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^\\+[1-9][0-9]{7,14}$" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactRestrictionBody" } } } }, "responses": { "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactProblem" } } } }, "403": { "description": "Insufficient permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactProblem" } } } }, "404": { "description": "Opaque reference or tenant mismatch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactProblem" } } } }, "409": { "description": "Changed effect or contention", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactProblem" } } } }, "422": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactProblem" } } } }, "201": { "description": "Restriction registered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactRestrictionEffect" } } } }, "200": { "description": "Successful replay or no-op", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactRestrictionEffect" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/contract-activations/lookup": { "get": { "tags": [ "Backoffice - Sales - ContractActivation Lookups" ], "summary": "Minimal contract-activations choices for tenant forms and filters", "operationId": "8bce8f676a68787290a8841f2b5601e9", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "to_approve", "active", "processed", "canceled", "ended" ] } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "maximum": 200, "minimum": 1 } }, { "name": "contract_id", "in": "query", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Only identity and displayed labels", "content": { "application/json": { "schema": { "required": [ "items", "total", "per_page", "current_page" ], "properties": { "items": { "type": "array", "items": { "required": [ "id", "code", "contract_code", "client_name" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "contract_code": { "type": "string", "nullable": true }, "client_name": { "type": "string", "nullable": true } }, "type": "object" } }, "total": { "type": "integer" }, "per_page": { "type": "integer" }, "current_page": { "type": "integer" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Tenant membership required" }, "422": { "description": "Invalid query" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/contract-activations/{id}/approve": { "post": { "tags": [ "Backoffice - Contract Activations" ], "summary": "Approve a contract activation", "operationId": "48d9feea4c8daf7293c8bffa000ddf78", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "financial_fingerprint": { "description": "Explicit acceptance of the current historical comparison", "type": "string", "pattern": "^[a-f0-9]{64}$", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Approved; JSON null" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } } } }, "403": { "description": "Missing permission or company membership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractActivationProblem" }, { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareForbiddenResponse" } ] } } } }, "400": { "description": "Activation cannot be approved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractActivationProblem" } } } }, "404": { "description": "Missing root or contract_line_not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractActivationProblem" } } } }, "409": { "description": "contract_not_vigente, contract_lifecycle_changed or contract_activation_rate_mismatch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractActivationProblem" } } } }, "422": { "description": "Invalid fields, or required/stale historical comparison; stale evidence never automatically approves", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractActivationProblem" }, { "$ref": "#/components/schemas/ContractActivationHistoricalDifference" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/contract-activations/{id}/cancel": { "post": { "tags": [ "Backoffice - Contract Activations" ], "summary": "Cancel a contract activation", "operationId": "9a840819da138c84071ee98c9d2070a9", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Completed" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } } } }, "403": { "description": "Missing permission or company membership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractActivationProblem" }, { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareForbiddenResponse" } ] } } } }, "400": { "description": "Activation cannot transition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractActivationProblem" } } } }, "404": { "description": "Contract or Activation not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractActivationProblem" } } } }, "409": { "description": "contract_not_vigente or contract_lifecycle_changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractActivationProblem" } } } }, "422": { "description": "Invalid Activation UUID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractActivationProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/contract-activations/source-contract/{id}": { "get": { "tags": [ "Backoffice - Sales - ContractActivations" ], "summary": "Source business facts for the consuming ContractActivations document", "operationId": "18d6343cef3aa0fad601c1daa05dc5a9", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Only source facts needed by this document; no source audit metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivationContractSource" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "The consuming document view or write permission is required" }, "404": { "description": "Source document not found in this company" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/contract-activations/{id}": { "get": { "tags": [ "Backoffice - Contract Activations" ], "summary": "Find a contract activation", "operationId": "311c082c755755e04207d9439a90fdb1", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Stored financial evidence with scoped metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractActivationRecord" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } } } }, "403": { "description": "Missing permission or company membership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractActivationProblem" }, { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareForbiddenResponse" } ] } } } }, "404": { "description": "Activation not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractActivationProblem" } } } }, "422": { "description": "Invalid Activation UUID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractActivationProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Backoffice - Contract Activations" ], "summary": "Update a contract activation", "operationId": "d2dbd846f720a50b5fdae8136dbc4e03", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractActivationUpdateRequest" } } } }, "responses": { "200": { "description": "Updated; JSON null" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } } } }, "403": { "description": "Missing permission or company membership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractActivationProblem" }, { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareForbiddenResponse" } ] } } } }, "404": { "description": "Contract, source line or Activation not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractActivationProblem" } } } }, "409": { "description": "contract_not_vigente, contract_lifecycle_changed or contract_activation_cannot_be_modified; preserve the user draft and offer explicit reload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractActivationProblem" } } } }, "422": { "description": "Dotted field errors or financial preview, tax selection and storage validation", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractActivationProblem" }, { "$ref": "#/components/schemas/ContractActivationFinancialValidation" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Backoffice - Contract Activations" ], "summary": "Delete a draft activation", "operationId": "cddbd70962b60325e43e0291af32b605", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Completed" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } } } }, "403": { "description": "Missing permission or company membership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractActivationProblem" }, { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareForbiddenResponse" } ] } } } }, "400": { "description": "Activation cannot transition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractActivationProblem" } } } }, "404": { "description": "Contract or Activation not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractActivationProblem" } } } }, "409": { "description": "contract_not_vigente or contract_lifecycle_changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractActivationProblem" } } } }, "422": { "description": "Invalid Activation UUID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractActivationProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/contract-activations": { "get": { "tags": [ "Backoffice - Contract Activations" ], "summary": "Search contract activations", "operationId": "4fc56b4f9254776dd8b8ac01600542b7", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Legacy scalar compatibility; OR within field, AND across fields", "schema": { "type": "string", "enum": [ "to_approve", "active", "processed", "canceled", "ended" ] } }, { "name": "status[]", "in": "query", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "to_approve", "active", "processed", "canceled", "ended" ] } } }, { "name": "contract_id", "in": "query", "description": "Legacy scalar compatibility; OR within field, AND across fields", "schema": { "type": "string", "format": "uuid" } }, { "name": "contract_id[]", "in": "query", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" } } }, { "name": "client_id", "in": "query", "description": "Legacy scalar compatibility; OR within field, AND across fields", "schema": { "type": "string", "format": "uuid" } }, { "name": "client_id[]", "in": "query", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" } } }, { "name": "label_ids", "in": "query", "description": "Legacy scalar compatibility; OR within field, AND across fields", "schema": { "type": "string", "format": "uuid" } }, { "name": "label_ids[]", "in": "query", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 20 } }, { "name": "search", "in": "query", "description": "Activation or company-scoped Contract code; explicit empty value overrides search_query", "schema": { "type": "string", "maxLength": 255 } }, { "name": "search_query", "in": "query", "description": "Legacy alias; search takes precedence", "schema": { "type": "string", "maxLength": 255 } }, { "name": "date_from", "in": "query", "description": "Inclusive start_date lower bound", "schema": { "type": "string", "format": "date" } }, { "name": "date_to", "in": "query", "description": "Inclusive due_date upper bound; cannot precede date_from", "schema": { "type": "string", "format": "date" } }, { "name": "activation_date_from", "in": "query", "description": "Inclusive activation_date lower bound", "schema": { "type": "string", "format": "date" } }, { "name": "activation_date_to", "in": "query", "description": "Inclusive activation_date upper bound; cannot precede activation_date_from", "schema": { "type": "string", "format": "date" } }, { "name": "sort_by", "in": "query", "description": "Default code DESC; stable id tie-break follows direction", "schema": { "type": "string", "enum": [ "activation_date", "billing_start_date", "code", "created_at" ] } }, { "name": "sort_order", "in": "query", "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "Enriched paginated rows and independent status and label facets", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractActivationListResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } } } }, "403": { "description": "Missing permission or company membership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractActivationProblem" }, { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareForbiddenResponse" } ] } } } }, "422": { "description": "Invalid query field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractActivationProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Contract Activations" ], "summary": "Create a contract activation", "operationId": "c5866de450e7226c8e9505beaf3dce71", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractActivationCreateRequest" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractActivationMutationResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } } } }, "403": { "description": "Missing permission or company membership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractActivationProblem" }, { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareForbiddenResponse" } ] } } } }, "404": { "description": "Contract, source line or Activation not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractActivationProblem" } } } }, "409": { "description": "contract_not_vigente, contract_lifecycle_changed or duplicate Activation ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractActivationProblem" } } } }, "422": { "description": "Dotted field errors or financial preview, tax selection and storage validation", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractActivationProblem" }, { "$ref": "#/components/schemas/ContractActivationFinancialValidation" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/contract-charges/{id}/cancel": { "post": { "tags": [ "Backoffice - Contract Charges" ], "summary": "ContractChargeCancelPost", "operationId": "642e674c54853d80688f14b0b1753697", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractChargeCancel" } } } }, "responses": { "200": { "description": "Success" }, "401": { "description": "Unauthenticated middleware", "content": { "application/json": { "schema": { "required": [ "message" ], "properties": { "message": { "type": "string" } }, "type": "object" } } } }, "403": { "description": "Missing permission", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractChargeProblem" }, { "required": [ "title", "status", "detail" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" } }, "type": "object" } ] } } } }, "422": { "description": "Invalid input or future charge date", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractChargeProblem" } } } }, "404": { "description": "Missing or foreign resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractChargeProblem" } } } }, "400": { "description": "State refusal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractChargeProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/contract-charges/{id}": { "get": { "tags": [ "Backoffice - Contract Charges" ], "summary": "ContractChargeGet", "operationId": "cf69fbc9f4740a3eddb40dea3e9b1e4b", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractChargeDetails" } } } }, "401": { "description": "Unauthenticated middleware", "content": { "application/json": { "schema": { "required": [ "message" ], "properties": { "message": { "type": "string" } }, "type": "object" } } } }, "403": { "description": "Missing permission", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractChargeProblem" }, { "required": [ "title", "status", "detail" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" } }, "type": "object" } ] } } } }, "422": { "description": "Invalid input or future charge date", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractChargeProblem" } } } }, "404": { "description": "Missing or foreign resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractChargeProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Backoffice - Contract Charges" ], "summary": "ContractChargeDelete", "operationId": "01a29d25d7bdc6082d79bd4ebe18c913", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Success" }, "401": { "description": "Unauthenticated middleware", "content": { "application/json": { "schema": { "required": [ "message" ], "properties": { "message": { "type": "string" } }, "type": "object" } } } }, "403": { "description": "Missing permission", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractChargeProblem" }, { "required": [ "title", "status", "detail" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" } }, "type": "object" } ] } } } }, "422": { "description": "Invalid input or future charge date", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractChargeProblem" } } } }, "404": { "description": "Missing or foreign resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractChargeProblem" } } } }, "400": { "description": "State refusal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractChargeProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/contract-charges": { "get": { "tags": [ "Backoffice - Contract Charges" ], "summary": "ContractChargesGet", "operationId": "5c6ac63e19370b1f0d44b88ca5ede867", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "to_be_invoiced", "invoiced", "cancelled" ] } }, { "name": "status[]", "in": "query", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "to_be_invoiced", "invoiced", "cancelled" ] } } }, { "name": "contract_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "contract_id[]", "in": "query", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" } } }, { "name": "client_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "client_id[]", "in": "query", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" } } }, { "name": "activation_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "date_from", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "date_to", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "search", "in": "query", "schema": { "type": "string", "maxLength": 255 } }, { "name": "search_query", "in": "query", "schema": { "type": "string", "maxLength": 255 } }, { "name": "group_by", "in": "query", "description": "Order complete status groups before pagination; omitted or none preserves ungrouped ordering.", "schema": { "type": "string", "enum": [ "status", "none" ] } }, { "name": "sort_by", "in": "query", "schema": { "type": "string", "default": "code", "enum": [ "charge_date", "code", "created_at" ] } }, { "name": "sort_order", "in": "query", "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractChargeList" } } } }, "401": { "description": "Unauthenticated middleware", "content": { "application/json": { "schema": { "required": [ "message" ], "properties": { "message": { "type": "string" } }, "type": "object" } } } }, "403": { "description": "Missing permission", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractChargeProblem" }, { "required": [ "title", "status", "detail" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" } }, "type": "object" } ] } } } }, "422": { "description": "Invalid input or future charge date", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractChargeProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Contract Charges" ], "summary": "ContractChargePost", "operationId": "e499bb0c3b7eba765669f8d44e9f340a", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractChargeCreate" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractChargeCreated" } } } }, "401": { "description": "Unauthenticated middleware", "content": { "application/json": { "schema": { "required": [ "message" ], "properties": { "message": { "type": "string" } }, "type": "object" } } } }, "403": { "description": "Missing permission", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractChargeProblem" }, { "required": [ "title", "status", "detail" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" } }, "type": "object" } ] } } } }, "422": { "description": "Invalid input or future charge date", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractChargeProblem" } } } }, "404": { "description": "Missing or foreign resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractChargeProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/contract-charges/sources/{source}/{id}": { "get": { "tags": [ "Backoffice - Sales - ContractCharges" ], "summary": "Source business facts for the consuming ContractCharges document", "operationId": "6abe7501734b06b61517dff9af0c1512", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "source", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "contract", "activation" ] } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Only source facts needed by this document; no source audit metadata", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ChargeContractSource" }, { "$ref": "#/components/schemas/ChargeActivationSource" } ] } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "The consuming document view or write permission is required" }, "404": { "description": "Source document not found in this company" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/contract-deactivations/{id}/approve": { "post": { "tags": [ "Backoffice - Contract Deactivations" ], "summary": "Approve a contract deactivation, settling its Charges through the inclusive deactivation date", "operationId": "c818f205871775bc39e7f8e9b2455e95", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "financial_fingerprint": { "description": "Required when stored header amounts differ from recalculation", "type": "string", "pattern": "^[a-f0-9]{64}$", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Contract deactivation approved successfully", "content": { "application/json": { "schema": { "properties": { "is_last_active_activation": { "type": "boolean" }, "contract_id": { "type": "string", "format": "uuid" }, "charges_generated_count": { "type": "integer" }, "charges_cancelled_count": { "type": "integer" }, "charges_invoiced_after_cutoff_count": { "type": "integer" } }, "type": "object" } } } }, "400": { "description": "Bad request - deactivation cannot be approved" }, "403": { "description": "Missing permission or company membership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractDeactivationProblem" }, { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareForbiddenResponse" } ] } } } }, "404": { "description": "Contract, activation, or deactivation not found" }, "409": { "description": "contract_not_vigente; contract_lifecycle_changed; contract_deactivation_date_in_future; contract_deactivation_charge_settlement_failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractDeactivationProblem" } } } }, "422": { "description": "Invalid fields; contract_deactivation_date_before_billing_start; or required/stale historical comparison, which requires the explicit current fingerprint", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractDeactivationProblem" }, { "$ref": "#/components/schemas/ContractDeactivationHistoricalDifference" } ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/contract-deactivations/{id}": { "get": { "tags": [ "Backoffice - Contract Deactivations" ], "summary": "Get a contract deactivation by ID", "operationId": "3e41d8679ea5e64afb909c2103f9ae7f", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Strict detail with company-scoped metadata and nullable captured approval evidence", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractDeactivationRecord" } } } }, "403": { "description": "Missing permission or company membership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractDeactivationProblem" }, { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareForbiddenResponse" } ] } } } }, "404": { "description": "Contract deactivation not found" }, "422": { "description": "Invalid path or query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractDeactivationProblem" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Backoffice - Contract Deactivations" ], "summary": "Update a contract deactivation", "operationId": "289d1dcfda017df9e284f3b1687ed715", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "deactivation_date" ], "properties": { "deactivation_date": { "type": "string", "format": "date" }, "observations": { "type": "string", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Contract deactivation updated successfully" }, "422": { "description": "Invalid path or body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractDeactivationProblem" } } } }, "403": { "description": "Missing permission or company membership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractDeactivationProblem" }, { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareForbiddenResponse" } ] } } } }, "404": { "description": "Contract, activation, or deactivation not found" }, "409": { "description": "contract_deactivation_cannot_be_modified, contract_not_vigente, contract_lifecycle_changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractDeactivationProblem" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Backoffice - Contract Deactivations" ], "summary": "Delete a contract deactivation", "operationId": "db9419d3b4a28c67d6c0cb81b15bcc8a", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Contract deactivation deleted successfully" }, "400": { "description": "Bad request" }, "403": { "description": "Missing permission or company membership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractDeactivationProblem" }, { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareForbiddenResponse" } ] } } } }, "404": { "description": "Contract, activation, or deactivation not found" }, "409": { "description": "Contract is not vigente or lifecycle changed" }, "422": { "description": "Invalid path or query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractDeactivationProblem" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/contract-deactivations": { "get": { "tags": [ "Backoffice - Contract Deactivations" ], "summary": "List contract deactivations with pagination and filters", "operationId": "c4f68f2874c0760f8acab5f77e4b905b", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Legacy scalar compatibility; OR within field, AND across fields", "schema": { "type": "string", "enum": [ "to_approve", "approved", "canceled" ] } }, { "name": "status[]", "in": "query", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "to_approve", "approved", "canceled" ] } } }, { "name": "contract_id", "in": "query", "description": "Legacy scalar compatibility; OR within field, AND across fields", "schema": { "type": "string", "format": "uuid" } }, { "name": "contract_id[]", "in": "query", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" } } }, { "name": "client_id", "in": "query", "description": "Legacy scalar compatibility; OR within field, AND across fields", "schema": { "type": "string", "format": "uuid" } }, { "name": "client_id[]", "in": "query", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" } } }, { "name": "label_ids", "in": "query", "description": "Legacy scalar compatibility; OR within field, AND across fields", "schema": { "type": "string", "format": "uuid" } }, { "name": "label_ids[]", "in": "query", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 20 } }, { "name": "search", "in": "query", "description": "DES, ACT or company-scoped CTR code; explicit empty value overrides search_query", "schema": { "type": "string", "maxLength": 255 } }, { "name": "search_query", "in": "query", "description": "Legacy alias; search takes precedence", "schema": { "type": "string", "maxLength": 255 } }, { "name": "date_from", "in": "query", "description": "Inclusive deactivation_date lower bound", "schema": { "type": "string", "format": "date" } }, { "name": "date_to", "in": "query", "description": "Inclusive deactivation_date upper bound; cannot precede date_from", "schema": { "type": "string", "format": "date" } }, { "name": "sort_by", "in": "query", "description": "Default code DESC; stable id tie-break follows direction", "schema": { "type": "string", "enum": [ "deactivation_date", "code", "created_at" ] } }, { "name": "sort_order", "in": "query", "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 100, "minimum": 1 } }, { "name": "activation_id", "in": "query", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Enriched rows, independent status and active-label facets", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractDeactivationListResponse" } } } }, "403": { "description": "Missing permission or company membership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractDeactivationProblem" }, { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareForbiddenResponse" } ] } } } }, "422": { "description": "Invalid path or query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractDeactivationProblem" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Contract Deactivations" ], "summary": "Create a new contract deactivation", "operationId": "2f008d52cd2af028b6e26ba3a96e421a", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "id", "activation_id", "deactivation_date" ], "properties": { "id": { "type": "string", "format": "uuid" }, "activation_id": { "type": "string", "format": "uuid" }, "deactivation_date": { "type": "string", "format": "date" }, "observations": { "type": "string", "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Contract deactivation created successfully", "content": { "application/json": { "schema": { "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "status": { "type": "string" } }, "type": "object" } } } }, "422": { "description": "Invalid path or body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractDeactivationProblem" } } } }, "403": { "description": "Missing permission or company membership", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractDeactivationProblem" }, { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareForbiddenResponse" } ] } } } }, "404": { "description": "Contract not found" }, "409": { "description": "activation_not_active_for_deactivation, pending_deactivation_already_exists, contract_not_vigente, contract_lifecycle_changed, contract_deactivation_already_exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractDeactivationProblem" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/contract-deactivations/source-activation/{id}": { "get": { "tags": [ "Backoffice - Sales - ContractDeactivations" ], "summary": "Source business facts for the consuming ContractDeactivations document", "operationId": "14de629277324c10e170ef1ee525787a", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Only source facts needed by this document; no source audit metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeactivationActivationSource" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "The consuming document view or write permission is required" }, "404": { "description": "Source document not found in this company" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/contracts/lookup": { "get": { "tags": [ "Backoffice - Sales - Contract Lookups" ], "summary": "Minimal contracts choices for tenant forms and filters", "operationId": "6611e36b781b5187f3247b8498c4a86b", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "to_approve", "vigente", "canceled" ] } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "maximum": 200, "minimum": 1 } } ], "responses": { "200": { "description": "Only identity and displayed labels", "content": { "application/json": { "schema": { "required": [ "items", "total", "per_page", "current_page" ], "properties": { "items": { "type": "array", "items": { "required": [ "id", "code", "client_name" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "client_name": { "type": "string", "nullable": true } }, "type": "object" } }, "total": { "type": "integer" }, "per_page": { "type": "integer" }, "current_page": { "type": "integer" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Tenant membership required" }, "422": { "description": "Invalid query" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/contracts/{id}/approve": { "post": { "tags": [ "Backoffice - Contracts" ], "summary": "Approve a contract", "operationId": "d726848853ed11e3aa396ffd4c4b57ab", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "financial_fingerprint": { "description": "Required when stored header amounts differ from the recalculation.", "type": "string", "pattern": "^[a-f0-9]{64}$", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Contract approved successfully" }, "409": { "description": "The contract can no longer be modified", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractProblemResponse" } } } }, "403": { "description": "Controller authorization or tenant-membership middleware", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractProblemResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareForbiddenResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } ] } } } }, "404": { "description": "Contract not found" }, "422": { "description": "Validation failure (ApiController) or historical comparison required/stale (exception renderer)", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractProblemResponse" }, { "$ref": "#/components/schemas/ContractHistoricalDifferenceResponse" }, { "$ref": "#/components/schemas/ContractFinancialValidationResponse" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/contracts/{id}/billing-defaults": { "patch": { "tags": [ "Backoffice - Sales Contracts" ], "summary": "Replace the billing defaults of a vigente sales contract", "operationId": "23167cb4888f1a2b81a337a4feb82744", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "billing_payment_term", "billing_account_receivable_id", "billing_location_id" ], "properties": { "billing_payment_term": { "description": "Must be sent with billing_account_receivable_id (both or neither).", "type": "string", "nullable": true, "maxLength": 255, "enum": [ "cash", "five_days", "seven_days", "fifteen_days", "thirty_days", null ] }, "billing_account_receivable_id": { "description": "Must be sent with billing_payment_term (both or neither).", "type": "string", "format": "uuid", "nullable": true }, "billing_location_id": { "description": "Prohibited unless both billing_payment_term and billing_account_receivable_id are present.", "type": "string", "format": "uuid", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Billing defaults replaced successfully", "content": { "application/json": { "schema": { "required": [ "id", "status", "billing_payment_term", "billing_account_receivable_id", "billing_location_id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "billing_payment_term": { "type": "string", "nullable": true, "maxLength": 255, "enum": [ "cash", "five_days", "seven_days", "fifteen_days", "thirty_days", null ] }, "billing_account_receivable_id": { "type": "string", "format": "uuid", "nullable": true }, "billing_location_id": { "type": "string", "format": "uuid", "nullable": true } }, "type": "object" } } } }, "400": { "description": "Incomplete billing defaults (incomplete_contract_billing_defaults)" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "404": { "description": "Contract not found (contract_not_found)" }, "409": { "description": "Contract is not vigente (contract_not_vigente)" }, "422": { "description": "Validation error" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/contracts/{id}/cancel": { "post": { "tags": [ "Backoffice - Contracts" ], "summary": "Cancel a vigente contract and its cancelable lifecycle graph", "operationId": "3c98174ec1ae833b9cf44a5c9727eaf7", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "impact_token" ], "properties": { "impact_token": { "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "description": "Contract canceled successfully" }, "403": { "description": "Forbidden" }, "404": { "description": "Contract not found" }, "409": { "description": "Contract is ineligible, its impact changed, or its cancellation graph is inconsistent" }, "422": { "description": "Malformed contract identifier or invalid cancellation impact token" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/contracts/{id}/cancellation-impact": { "get": { "tags": [ "Backoffice - Contracts" ], "summary": "Preview a contract cancellation impact", "operationId": "ce7e26694926fa97fbb2707febe2230b", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Cancellation impact preview", "content": { "application/json": { "schema": { "required": [ "contract", "impact", "impact_token" ], "properties": { "contract": { "required": [ "id", "code", "status" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "status": { "type": "string", "example": "vigente" } }, "type": "object" }, "impact": { "required": [ "active_activations", "to_approve_activations", "to_approve_deactivations", "active_charge_recurrence_rules_count" ], "properties": { "active_activations": { "type": "array", "items": { "required": [ "id", "code", "status", "activation_date" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "status": { "type": "string", "example": "active" }, "activation_date": { "type": "string", "format": "date" } }, "type": "object" } }, "to_approve_activations": { "type": "array", "items": { "required": [ "id", "code", "status", "activation_date" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "status": { "type": "string", "example": "to_approve" }, "activation_date": { "type": "string", "format": "date" } }, "type": "object" } }, "to_approve_deactivations": { "type": "array", "items": { "required": [ "id", "code", "status", "deactivation_date", "activation_id", "activation_code" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "status": { "type": "string", "example": "to_approve" }, "deactivation_date": { "type": "string", "format": "date" }, "activation_id": { "type": "string", "format": "uuid" }, "activation_code": { "type": "string" } }, "type": "object" } }, "active_charge_recurrence_rules_count": { "type": "integer", "example": 0 } }, "type": "object" }, "impact_token": { "type": "string" } }, "type": "object" } } } }, "403": { "description": "Forbidden" }, "404": { "description": "Contract not found" }, "409": { "description": "Contract is ineligible or its cancellation graph is inconsistent" }, "422": { "description": "Malformed contract identifier" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/contracts/{id}": { "get": { "tags": [ "Backoffice - Contracts" ], "summary": "Get a contract by ID", "operationId": "ff697b21eae77d94e8c345fbb6da01f1", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Contract found", "content": { "application/json": { "schema": { "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "client_name": { "type": "string", "nullable": true }, "responsible_user_id": { "type": "string", "nullable": true, "maxLength": 255 }, "responsible_user_name": { "type": "string", "nullable": true }, "labels": { "type": "array", "items": { "required": [ "id", "name", "tone", "archived" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "tone": { "type": "string", "enum": [ "red", "orange", "blue", "violet", "teal" ] }, "archived": { "type": "boolean" } }, "type": "object" } }, "created_at": { "description": "Persisted audit timestamp; null when unavailable on a legacy record.", "type": "string", "format": "date-time", "nullable": true }, "updated_at": { "description": "Persisted audit timestamp; null when unavailable on a legacy record.", "type": "string", "format": "date-time", "nullable": true }, "accounting_center_name": { "type": "string", "nullable": true }, "billing_account_receivable_name": { "type": "string", "nullable": true }, "billing_location_name": { "type": "string", "nullable": true }, "client_id": { "type": "string", "format": "uuid" }, "start_date": { "type": "string", "format": "date" }, "due_date": { "type": "string", "format": "date" }, "recurring_billing": { "type": "string" }, "accounting_center_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "reference": { "type": "string", "nullable": true }, "subtotal": { "type": "string", "example": "1000.00" }, "discount": { "type": "string", "example": "0.00" }, "taxes": { "type": "string", "example": "160.00" }, "total": { "type": "string", "example": "1160.00" }, "observations": { "type": "string", "nullable": true }, "billing_payment_term": { "description": "Null until the contract's billing defaults are set.", "type": "string", "nullable": true, "enum": [ "cash", "five_days", "seven_days", "fifteen_days", "thirty_days", null ] }, "billing_account_receivable_id": { "type": "string", "format": "uuid", "nullable": true }, "billing_location_id": { "type": "string", "format": "uuid", "nullable": true }, "company_id": { "type": "string", "format": "uuid" }, "automation_blocked": { "type": "boolean", "nullable": false }, "automation_block_reasons": { "type": "array", "items": { "type": "string", "enum": [ "billing_defaults_missing", "contract_not_vigente", "tax_not_found", "unexpected_failure" ] } }, "automation_block_stages": { "type": "array", "items": { "type": "string", "enum": [ "charge_generation", "invoicing" ] } }, "automation_block_resolutions": { "type": "array", "items": { "required": [ "stage", "resolution", "resolved_at", "resolved_by" ], "properties": { "stage": { "type": "string", "enum": [ "charge_generation", "invoicing" ] }, "period_key": { "type": "string", "nullable": true }, "resolution": { "type": "string", "enum": [ "invoiced", "charges_generated", "charges_cancelled", "stale", "manually_invoiced" ] }, "resolved_at": { "type": "string", "format": "date-time" }, "resolved_by": { "description": "The id of the user who resolved the block, or system for the nightly run. A block a person invoiced before MER-5667 reads system.", "type": "string" }, "resolution_detail": { "description": "The reason of the cancellation or override that resolved the block; null otherwise.", "type": "string", "nullable": true } }, "type": "object" } }, "items": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "category_id": { "type": "string", "format": "uuid" }, "item_id": { "type": "string", "format": "uuid" }, "item_name": { "type": "string" }, "accounting_center_id": { "type": "string", "format": "uuid", "nullable": true }, "quantity": { "type": "string", "example": "1.00" }, "tariff_period": { "type": "string" }, "agreed_rate": { "type": "string", "example": "1000.00" }, "subtotal": { "type": "string", "example": "1000.00" }, "tax_id": { "type": "string", "format": "uuid" }, "tax_percentage": { "type": "string", "example": "16.00" }, "discount_percentage": { "type": "string", "example": "0.00" }, "accounting_account_id": { "type": "string", "format": "uuid" } }, "type": "object" } } }, "type": "object" } } } }, "403": { "description": "Permission or tenant-membership middleware", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractProblemResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareForbiddenResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } ] } } } }, "404": { "description": "Contract not found or foreign", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractProblemResponse" } } } }, "401": { "description": "Authentication middleware", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } } } }, "422": { "description": "Controller validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractProblemResponse" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Backoffice - Contracts" ], "summary": "Update a contract", "operationId": "327e4015f3a4cb44b0a8fab8a1544ad9", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "client_id", "start_date", "due_date", "recurring_billing", "accounting_center_id", "items" ], "properties": { "client_id": { "type": "string", "format": "uuid" }, "start_date": { "type": "string", "format": "date" }, "due_date": { "type": "string", "format": "date" }, "recurring_billing": { "type": "string", "enum": [ "daily", "semi_monthly", "monthly", "annually" ] }, "accounting_center_id": { "type": "string", "format": "uuid" }, "reference": { "type": "string", "nullable": true, "maxLength": 255 }, "observations": { "type": "string", "nullable": true }, "billing_payment_term": { "description": "Optional. Must be sent with billing_account_receivable_id (both or neither).", "type": "string", "nullable": true, "maxLength": 255, "enum": [ "cash", "five_days", "seven_days", "fifteen_days", "thirty_days", null ] }, "billing_account_receivable_id": { "description": "Optional. Must be sent with billing_payment_term (both or neither).", "type": "string", "format": "uuid", "nullable": true }, "billing_location_id": { "description": "Optional. Prohibited unless both billing_payment_term and billing_account_receivable_id are present.", "type": "string", "format": "uuid", "nullable": true }, "items": { "type": "array", "items": { "required": [ "id", "category_id", "item_id", "item_name", "quantity", "tariff_period", "agreed_rate", "tax_id", "tax_percentage", "discount_percentage", "accounting_account_id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "category_id": { "type": "string", "format": "uuid" }, "item_id": { "type": "string", "format": "uuid" }, "item_name": { "type": "string", "maxLength": 255 }, "quantity": { "type": "string", "pattern": "^[0-9]+([.][0-9]{1,4})?$", "example": "10.0000" }, "tariff_period": { "type": "string", "enum": [ "semi_monthly", "monthly", "annually" ] }, "agreed_rate": { "type": "string", "pattern": "^[0-9]+([.][0-9]{1,2})?$", "example": "25.50" }, "tax_id": { "type": "string", "format": "uuid" }, "tax_percentage": { "type": "string", "pattern": "^(?:0*(?:[0-9]|[1-9][0-9])(?:[.][0-9]{1,2})?|0*100(?:[.]0{1,2})?)$", "example": "16.00" }, "discount_percentage": { "type": "string", "pattern": "^(?:0*(?:[0-9]|[1-9][0-9])(?:[.][0-9]{1,2})?|0*100(?:[.]0{1,2})?)$", "example": "0.00" }, "accounting_account_id": { "type": "string", "format": "uuid" }, "accounting_center_id": { "type": "string", "format": "uuid", "nullable": true } }, "type": "object" } }, "preview": { "description": "Optional scale-2 preview. String amounts only. Null skips the comparison.", "properties": { "subtotal": { "type": "string", "pattern": "^[0-9]+(?:[.][0-9]{1,2})?$" }, "discount": { "type": "string", "pattern": "^[0-9]+(?:[.][0-9]{1,2})?$" }, "taxes": { "type": "string", "pattern": "^[0-9]+(?:[.][0-9]{1,2})?$" }, "total": { "type": "string", "pattern": "^[0-9]+(?:[.][0-9]{1,2})?$" }, "tax_groups": { "type": "array", "items": { "properties": { "tax_id": { "type": "string", "format": "uuid" }, "tax_percentage": { "type": "string" }, "base": { "type": "string" }, "tax": { "type": "string" } }, "type": "object" } } }, "type": "object", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Contract updated successfully", "content": { "application/json": { "schema": { "type": "object" } } } }, "409": { "description": "Contract cannot be modified in its current state; commercial PUT preserves the responsible user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractProblemResponse" } } } }, "403": { "description": "Controller authorization or tenant-membership middleware", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractProblemResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareForbiddenResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } ] } } } }, "404": { "description": "Contract not found" }, "422": { "description": "Controller validation Problem or financial-domain exception-renderer payload", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractProblemResponse" }, { "$ref": "#/components/schemas/ContractFinancialValidationResponse" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Backoffice - Contracts" ], "summary": "Delete a contract", "operationId": "bb7bb3fa015b4daf643fff90f626c8df", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Contract deleted successfully" }, "422": { "description": "Controller validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractProblemResponse" } } } }, "403": { "description": "Controller authorization or tenant-membership middleware", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractProblemResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareForbiddenResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } ] } } } }, "404": { "description": "Contract not found" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/contracts": { "get": { "tags": [ "Backoffice - Contracts" ], "summary": "List contracts with pagination and filters", "operationId": "b6b74ad4a1dceeadaaa10decaf85fc8e", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1 } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "to_approve", "vigente", "canceled" ] } }, { "name": "client_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "status[]", "in": "query", "description": "OR within this field; AND with other filters. Empty array means unrestricted.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "to_approve", "vigente", "canceled" ] } } }, { "name": "client_id[]", "in": "query", "description": "OR within this field; AND with other filters. Empty array means unrestricted.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" } } }, { "name": "responsible_user_id[]", "in": "query", "description": "OR within this field; AND with other filters. Empty array means unrestricted.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "pattern": "^[1-9][0-9]*$", "maxLength": 255 } } }, { "name": "label_ids[]", "in": "query", "description": "OR within this field; AND with other filters. Empty array means unrestricted.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" } } }, { "name": "search", "in": "query", "description": "Code or reference text. Wins over search_query, including explicit empty search.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "search_query", "in": "query", "description": "Legacy text alias used only when search is absent.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "reference", "in": "query", "schema": { "type": "string", "maxLength": 255 } }, { "name": "accounting_center_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "sort_by", "in": "query", "description": "Default code; selected field and id tie-break in the same direction.", "schema": { "type": "string", "default": "code", "enum": [ "start_date", "due_date", "code", "created_at" ] } }, { "name": "sort_order", "in": "query", "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } }, { "name": "code", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "recurring_billing", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "daily", "semi_monthly", "monthly", "annually" ] } }, { "name": "date_from", "in": "query", "description": "Inclusive start_date greater than or equal to this date.", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "date_to", "in": "query", "description": "Inclusive due_date less than or equal to this date.", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "automation_blocked", "in": "query", "description": "Filter Contracts by automation block state: true (unresolved blocks), false (no unresolved blocks), or resolved (resolved-only history)", "required": false, "schema": { "type": "string", "enum": [ "true", "false", "1", "0", "resolved" ] } } ], "responses": { "200": { "description": "Contracts list", "content": { "application/json": { "schema": { "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "required": [ "id", "code", "client_id", "start_date", "due_date", "recurring_billing", "accounting_center_id", "status", "reference", "subtotal", "discount", "taxes", "total", "observations", "billing_payment_term", "billing_account_receivable_id", "billing_location_id", "company_id", "items", "automation_blocked", "automation_block_reasons", "automation_block_stages", "automation_block_resolutions", "responsible_user_id", "client_name", "responsible_user_name", "labels" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "client_name": { "type": "string", "nullable": true }, "responsible_user_id": { "type": "string", "nullable": true, "maxLength": 255 }, "responsible_user_name": { "type": "string", "nullable": true }, "labels": { "type": "array", "items": { "required": [ "id", "name", "tone", "archived" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "tone": { "type": "string", "enum": [ "red", "orange", "blue", "violet", "teal" ] }, "archived": { "type": "boolean" } }, "type": "object" } }, "client_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "start_date": { "type": "string", "format": "date" }, "due_date": { "type": "string", "format": "date" }, "recurring_billing": { "type": "string", "enum": [ "daily", "semi_monthly", "monthly", "annually" ] }, "accounting_center_id": { "type": "string", "format": "uuid" }, "reference": { "type": "string", "nullable": true }, "subtotal": { "type": "string", "example": "1000.00" }, "discount": { "type": "string", "example": "0.00" }, "taxes": { "type": "string", "example": "160.00" }, "total": { "type": "string", "example": "1160.00" }, "observations": { "type": "string", "nullable": true }, "billing_payment_term": { "description": "Null until the billing defaults are set. The list reads stored rows, so a stored value outside the five is echoed as stored: an integrity incident to repair (ADR 0299), never a sixth term.", "type": "string", "nullable": true, "enum": [ "cash", "five_days", "seven_days", "fifteen_days", "thirty_days", null ] }, "billing_account_receivable_id": { "type": "string", "format": "uuid", "nullable": true }, "billing_location_id": { "type": "string", "format": "uuid", "nullable": true }, "company_id": { "type": "string", "format": "uuid" }, "items": { "type": "array", "items": { "required": [ "id", "category_id", "item_id", "item_name", "quantity", "tariff_period", "agreed_rate", "subtotal", "tax_id", "tax_percentage", "discount_percentage", "accounting_account_id", "accounting_center_id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "category_id": { "type": "string", "format": "uuid" }, "item_id": { "type": "string", "format": "uuid" }, "item_name": { "type": "string" }, "quantity": { "type": "string", "example": "10.00" }, "tariff_period": { "type": "string", "enum": [ "semi_monthly", "monthly", "annually" ] }, "agreed_rate": { "type": "string", "example": "25.50" }, "subtotal": { "type": "string", "example": "255.00" }, "tax_id": { "type": "string", "format": "uuid" }, "tax_percentage": { "type": "string", "example": "16.00" }, "discount_percentage": { "type": "string", "example": "0.00" }, "accounting_account_id": { "type": "string", "format": "uuid" }, "accounting_center_id": { "type": "string", "format": "uuid", "nullable": true } }, "type": "object" } }, "automation_blocked": { "type": "boolean", "nullable": false }, "automation_block_reasons": { "type": "array", "items": { "type": "string", "enum": [ "billing_defaults_missing", "contract_not_vigente", "tax_not_found", "unexpected_failure" ] } }, "automation_block_stages": { "type": "array", "items": { "type": "string", "enum": [ "charge_generation", "invoicing" ] } }, "automation_block_resolutions": { "type": "array", "items": { "required": [ "stage", "resolution", "resolved_at", "resolved_by" ], "properties": { "stage": { "type": "string", "enum": [ "charge_generation", "invoicing" ] }, "period_key": { "type": "string", "nullable": true }, "resolution": { "type": "string", "enum": [ "invoiced", "charges_generated", "charges_cancelled", "stale", "manually_invoiced" ] }, "resolved_at": { "type": "string", "format": "date-time" }, "resolved_by": { "description": "The id of the user who resolved the block, or system for the nightly run. A block a person invoiced before MER-5667 reads system.", "type": "string" }, "resolution_detail": { "description": "The reason of the cancellation or override that resolved the block; null otherwise.", "type": "string", "nullable": true } }, "type": "object" } } }, "type": "object" } }, "meta": { "required": [ "total", "per_page", "current_page", "counts", "label_counts" ], "properties": { "total": { "type": "integer" }, "per_page": { "type": "integer" }, "current_page": { "type": "integer" }, "counts": { "description": "All matching roots with only status removed.", "required": [ "to_approve", "vigente", "canceled" ], "properties": { "to_approve": { "type": "integer" }, "vigente": { "type": "integer" }, "canceled": { "type": "integer" } }, "type": "object" }, "label_counts": { "description": "Distinct root counts with only labels removed; excludes archived labels. Empty is an object.", "type": "object", "additionalProperties": { "type": "integer" } } }, "type": "object" } }, "type": "object" } } } }, "422": { "description": "Malformed search criteria", "content": { "application/json": { "schema": { "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string", "example": "The given data was invalid." }, "error_code": { "type": "string", "nullable": true }, "errors": { "type": "object" } }, "type": "object" } } } }, "403": { "description": "Permission or tenant-membership middleware", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractProblemResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareForbiddenResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } ] } } } }, "401": { "description": "Authentication middleware", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Contracts" ], "summary": "Create a new contract", "operationId": "618fe971e2c3a03c63f7d6f69578cb02", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "id", "client_id", "start_date", "due_date", "recurring_billing", "accounting_center_id", "items" ], "properties": { "id": { "type": "string", "format": "uuid" }, "responsible_user_id": { "description": "Optional company member user id; null means unassigned.", "type": "string", "pattern": "^[1-9][0-9]*$", "nullable": true, "maxLength": 255 }, "client_id": { "type": "string", "format": "uuid" }, "start_date": { "type": "string", "format": "date" }, "due_date": { "type": "string", "format": "date" }, "recurring_billing": { "type": "string", "enum": [ "daily", "semi_monthly", "monthly", "annually" ] }, "accounting_center_id": { "type": "string", "format": "uuid" }, "reference": { "type": "string", "nullable": true, "maxLength": 255 }, "observations": { "type": "string", "nullable": true }, "billing_payment_term": { "description": "Optional. Must be sent with billing_account_receivable_id (both or neither).", "type": "string", "nullable": true, "maxLength": 255, "enum": [ "cash", "five_days", "seven_days", "fifteen_days", "thirty_days", null ] }, "billing_account_receivable_id": { "description": "Optional. Must be sent with billing_payment_term (both or neither).", "type": "string", "format": "uuid", "nullable": true }, "billing_location_id": { "description": "Optional. Prohibited unless both billing_payment_term and billing_account_receivable_id are present.", "type": "string", "format": "uuid", "nullable": true }, "items": { "type": "array", "items": { "required": [ "id", "category_id", "item_id", "item_name", "quantity", "tariff_period", "agreed_rate", "tax_id", "tax_percentage", "discount_percentage", "accounting_account_id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "category_id": { "type": "string", "format": "uuid" }, "item_id": { "type": "string", "format": "uuid" }, "item_name": { "type": "string", "maxLength": 255 }, "quantity": { "type": "string", "pattern": "^[0-9]+([.][0-9]{1,4})?$", "example": "10.0000" }, "tariff_period": { "type": "string", "enum": [ "semi_monthly", "monthly", "annually" ] }, "agreed_rate": { "type": "string", "pattern": "^[0-9]+([.][0-9]{1,2})?$", "example": "25.50" }, "tax_id": { "type": "string", "format": "uuid" }, "tax_percentage": { "type": "string", "pattern": "^(?:0*(?:[0-9]|[1-9][0-9])(?:[.][0-9]{1,2})?|0*100(?:[.]0{1,2})?)$", "example": "16.00" }, "discount_percentage": { "type": "string", "pattern": "^(?:0*(?:[0-9]|[1-9][0-9])(?:[.][0-9]{1,2})?|0*100(?:[.]0{1,2})?)$", "example": "0.00" }, "accounting_account_id": { "type": "string", "format": "uuid" }, "accounting_center_id": { "type": "string", "format": "uuid", "nullable": true } }, "type": "object" } }, "preview": { "description": "Optional scale-2 preview. String amounts only. Null skips the comparison.", "properties": { "subtotal": { "type": "string", "pattern": "^[0-9]+(?:[.][0-9]{1,2})?$" }, "discount": { "type": "string", "pattern": "^[0-9]+(?:[.][0-9]{1,2})?$" }, "taxes": { "type": "string", "pattern": "^[0-9]+(?:[.][0-9]{1,2})?$" }, "total": { "type": "string", "pattern": "^[0-9]+(?:[.][0-9]{1,2})?$" }, "tax_groups": { "type": "array", "items": { "properties": { "tax_id": { "type": "string", "format": "uuid" }, "tax_percentage": { "type": "string" }, "base": { "type": "string" }, "tax": { "type": "string" } }, "type": "object" } } }, "type": "object", "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Contract created successfully", "content": { "application/json": { "schema": { "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "status": { "type": "string" } }, "type": "object" } } } }, "409": { "description": "Existing contract ID (contract_already_exists) or incompatible state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractProblemResponse" } } } }, "403": { "description": "Controller authorization or tenant-membership middleware", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractProblemResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareForbiddenResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } ] } } } }, "422": { "description": "Controller validation Problem or financial-domain exception-renderer payload", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractProblemResponse" }, { "$ref": "#/components/schemas/ContractFinancialValidationResponse" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/contracts/{id}/responsible": { "put": { "tags": [ "Backoffice - Contracts" ], "summary": "Reassign the responsible user of a contract", "operationId": "1357b8c0943da9a6053df1ea76e23eff", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "responsible_user_id" ], "properties": { "responsible_user_id": { "description": "Company user id that becomes the Contract Responsable; null clears it", "type": "string", "pattern": "^[1-9][0-9]*$", "nullable": true, "maxLength": 255 } }, "type": "object" } } } }, "responses": { "200": { "description": "Responsible reassigned" }, "403": { "description": "Permission middleware or controller authorization.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractProblemResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareForbiddenResponse" }, { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } ] } } } }, "404": { "description": "Absent or foreign Contract returns the controller Problem; malformed UUID returns the router message.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" }, { "$ref": "#/components/schemas/ContractProblemResponse" } ] } } } }, "409": { "description": "Responsible cannot be reassigned in the current status", "content": { "application/json": { "schema": { "properties": { "error_code": { "type": "string", "example": "contract_responsible_cannot_be_reassigned" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string" }, "error_code": { "type": "string", "nullable": true }, "errors": { "type": "object" } }, "type": "object" } } } }, "401": { "description": "Authentication middleware", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractMiddlewareMessageResponse" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/contracts/{contractId}/invoice-charges-override": { "post": { "tags": [ "Backoffice - Contracts" ], "summary": "Invoice open charges on a non-vigente contract with a typed override", "operationId": "164442fac4c35f99c3c8882770967256", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "contractId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "invoice_id", "reason" ], "properties": { "invoice_id": { "description": "Client-generated invoice UUID. Supply a new id for each billed-period drain while open charges remain; reusing an id that already exists returns 409. Retrying after every open charge is invoiced returns 400 `no_charges_to_invoice` regardless of the id.", "type": "string", "format": "uuid" }, "reason": { "description": "Mandatory justification. It is kept on the automation block this call resolves, also on a vigente contract, where the call invoices as the manual route does.", "type": "string", "maxLength": 500, "minLength": 1 } }, "type": "object" } } } }, "responses": { "201": { "description": "Sales invoice created from the oldest open billed period", "content": { "application/json": { "schema": { "properties": { "id": { "type": "string", "format": "uuid" }, "emission_date": { "type": "string", "format": "date" }, "has_more_open_periods": { "type": "boolean" } }, "type": "object" } } } }, "400": { "description": "No charges to invoice (`no_charges_to_invoice`), or an invalid override reason at the domain boundary" }, "403": { "description": "Unauthorized" }, "404": { "description": "Contract not found" }, "409": { "description": "Charge cannot be invoiced, invoice id already exists, or contract billing defaults are missing (`contract_billing_defaults_missing`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractProblemResponse" } } } }, "422": { "description": "Request validation failed (errors keyed by field), or a charge line whose tax the catalog does not hold, which answers {error: sales_invoice_tax_selection_invalid, detail, tax_ids} and writes nothing", "content": { "application/json": { "schema": { "oneOf": [ { "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422, "enum": [ 422 ] }, "detail": { "type": "string", "example": "The given data was invalid." }, "error_code": { "description": "Null for request validation.", "type": "string", "example": null, "nullable": true }, "errors": { "description": "Field-keyed validation messages.", "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" }, { "$ref": "#/components/schemas/ContractFinancialValidationResponse" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/contracts/{contractId}/invoice-charges": { "post": { "tags": [ "Backoffice - Contracts" ], "summary": "Create a sales invoice from contract charges", "operationId": "8f49b15608879985715e03efa81c1d0e", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "contractId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "id", "payment_term", "emission_date", "accounting_account_receivable_id" ], "properties": { "id": { "description": "Identifier of the invoice to create. It is NOT an idempotency key: every drain call must supply a NEW id, including a retry of a call whose response was lost. Reusing the id of an already created invoice is rejected with 409 sales_invoice_already_exists.", "type": "string", "format": "uuid" }, "payment_term": { "description": "Required. The Payment Term the invoice is issued with, one of the five. It never falls back to the contract's billing_payment_term: the manual drain stamps exactly the term the caller sends (MER-4368).", "type": "string", "enum": [ "cash", "five_days", "seven_days", "fifteen_days", "thirty_days" ] }, "emission_date": { "description": "Ignored. The emission date is derived from the charge date of the billed period this call drains.", "type": "string", "format": "date", "deprecated": true }, "accounting_account_receivable_id": { "type": "string", "format": "uuid" }, "location_id": { "type": "string", "format": "uuid", "nullable": true }, "reference": { "type": "string", "nullable": true, "maxLength": 255 } }, "type": "object" } } } }, "responses": { "201": { "description": "Sales invoice created from the oldest open billed period", "content": { "application/json": { "schema": { "properties": { "id": { "type": "string", "format": "uuid" }, "emission_date": { "description": "General-ledger posting date, derived from the charge date of the drained billed period.", "type": "string", "format": "date" }, "has_more_open_periods": { "description": "True when the contract still owes older-to-newer billed periods; call again to drain the next one, supplying a NEW id on every call.", "type": "boolean" } }, "type": "object" } } } }, "400": { "description": "No open charge to invoice (no_charges_to_invoice)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractProblemResponse" } } } }, "403": { "description": "Unauthorized" }, "404": { "description": "Contract not found" }, "409": { "description": "Charge cannot be invoiced, or the supplied id already belongs to a sales invoice" }, "422": { "description": "Validation error with field-keyed errors and a null error_code (for example a payment_term outside the five), the contract is not vigente (contract_not_vigente), or a charge line whose tax the catalog does not hold, which answers {error: sales_invoice_tax_selection_invalid, detail, tax_ids} and writes nothing", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContractProblemResponse" }, { "$ref": "#/components/schemas/ContractFinancialValidationResponse" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/pos/sales": { "get": { "tags": [ "Backoffice - Sales - Counter Sales" ], "summary": "List a Turno's counter sales", "description": "The ventas del turno (MER-4975): one page of the Venta de mostrador sales charged on a Turno of the company, newest first (sold_at, then id, both descending), whichever Vendedora sold them. A Turno without sales answers an empty page; an unknown Turno and another company's answer the same 404 cash_shift_not_found. Blank query values count as absent. meta.counts counts every sale of the Turno by status, on every page (MER-5151). Requires backoffice.sales.counter-sales.view; a POS session token reaches it. A plain read with no lock.", "operationId": "bbb5fba20de5a86008e76e9f9c27fffc", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "cash_shift_id", "in": "query", "description": "The Turno whose sales to list.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1, "maximum": 1000, "minimum": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "The page", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CounterSaleViewPage" } } } }, "401": { "description": "Unauthenticated: the auth middleware answers before the controller", "content": { "application/json": { "schema": { "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "403": { "description": "Without backoffice.sales.counter-sales.view, or a caller who does not belong to the company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CounterSaleProblem" } } } }, "404": { "description": "cash_shift_not_found: no such Turno in the company, the same answer for another company's; or the middleware's answer for a tenant the caller or the POS token does not reach", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CounterSaleProblem" } } } }, "422": { "description": "cash_shift_id is missing or not a UUID, page is outside 1 to 1000, or per_page is outside 1 to 100 (errors names the parameter)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CounterSaleProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Sales - Counter Sales" ], "summary": "Charge a counter sale", "description": "Charges a Venta de mostrador (MER-4974, ADR 0311 amended by ADR 0318) in one transaction: it locks the Caja's open Turno, claims the idempotency key, quotes again with the same body and compares the till's quote_fingerprint, creates and approves a cash Sales Invoice of the Caja's Canal and Location (its prices guarded against the Canal's default list, so a Vendedora without backoffice.sales.price-lists.override sells at the Canal price), dispatches every line in full (the Reservas consumed, stock lowered, cost of sale posted) and applies one Collection with a method line per payment, attributed to the Turno. Any failure rolls everything back: nothing is visible before it commits. The invoice, the collection and the sale are dated the quote's company day. The idempotency key is unique per company: the same Vendedora resending the same body under it answers 200 with the same body, another body or another Vendedora answers 409 idempotency_key_conflict. A retry is checked against the Caja as it is now, before its key: it needs the Turno still open and the Caja still selling (active, with an active POS Canal), or it answers 409 cash_shift_not_open or 422 counter_sale_cash_register_not_selling instead of the replay; GET pos/sales/lookup recovers the sale either way. A replay or a lookup of a sale voided since answers the charge it froze, unchanged; the sale's state is on its receipt (MER-4978). The Vendedora is the authenticated user, never a body field. Payments must settle the total within the collection's tolerance; there is no change. Every rail but cash requires its reference. A non-null web_order_id charges a Pedido web this seller holds, on the Turno that claimed it (MER-5432, ADR 0361-a-pos-charge, ADR 0362): Turno, key, then the order row; the invoice copies its frozen prices and taxes to its Client on this Canal, its Reservas move to the sale under the stock locks with Reservado unchanged, and the order ends charged_in_store, linked to the sale, its invoice and its collection. It also requires backoffice.sales.web-orders.claim, before its body is validated. A void of that sale gives the stock back and never reopens the order. Requires backoffice.sales.counter-sales.sell; a POS session token reaches it.", "operationId": "6c15d7b0f261fe3c04e1bf009238fb1c", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CounterSaleChargeRequest" }, { "$ref": "#/components/schemas/WebOrderCounterSaleChargeRequest" } ] } } } }, "responses": { "201": { "description": "The sale was charged", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CounterSale" } } } }, "200": { "description": "The same Vendedora resent the same body under the key: the sale it charged, the same body as its 201", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CounterSale" } } } }, "401": { "description": "Unauthenticated: the auth middleware answers before the controller", "content": { "application/json": { "schema": { "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "403": { "description": "Without backoffice.sales.counter-sales.sell, or a caller who does not belong to the company; or, naming a Pedido web, without backoffice.sales.web-orders.claim", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CounterSaleProblem" } } } }, "404": { "description": "cash_register_not_found: an unknown Caja or another company's; web_order_not_found: unknown, or of another company or Location, the same answer for each; or the middleware's answer for a tenant the caller or the POS token does not reach", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CounterSaleProblem" } } } }, "409": { "description": "cash_shift_not_open (with cash_register_id): the Caja has no open Turno, or a close won it; idempotency_key_conflict: the key charged another body or another Vendedora's sale; quote_changed (with the fresh quote): a rate, a price, a tax or an IGTF changed since the till quoted; insufficient_stock (with insufficient_stock_items) when the Disponible no longer covers a line; multiple_insufficient_stock when a line's exit finds less on hand than it needs: with reservations off, or a Pedido web whose on-hand fell below its hold, a definite refusal that leaves its claim, hold and deadline intact. Naming a Pedido web: web_order_already_charged (with charged_sale, order_status, current_version, expires_at and claim); web_order_expired, web_order_not_chargeable, web_order_version_conflict, web_order_not_claimed, web_order_claim_conflict: another seller, cycle or Turno, so another Caja at the same Location (each with order_status, current_version, expires_at and claim); web_order_hold_mismatch: its Reservas no longer match its lines", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CounterSaleProblem" }, { "$ref": "#/components/schemas/CounterSaleQuoteChangedProblem" }, { "$ref": "#/components/schemas/WebOrderQueueProblem" } ] } } } }, "422": { "description": "Request validation failed (errors names each field); counter_sale_cash_register_not_selling (with reason); counter_sale_item_not_found (with lines); counter_sale_line_unpriced (with lines[index, item_id, status]); counter_sale_line_not_chargeable (with lines[index, item_id, blocked_by]); counter_sale_payment_reference_required (errors names payments.N.reference); counter_sale_payments_do_not_settle (with remaining and settlement); counter_sale_receivable_account_missing; counter_sale_client_not_found; client_fiscal_identity_incomplete (with missing only): a Pedido web's Client cannot be invoiced, or it has none; sales_invoice_tax_selection_invalid: a tax it froze is no longer in the catalog; invalid_counter_buyer, invalid_cedula, invalid_rif or invalid_passport; counter_sale_payment_instrument_not_a_rail (with payments); a collection instrument or settlement error when an instrument changed meanwhile; an inventory configuration error of the dispatch; or {error: accounting_configuration_incomplete, missing[]} when the invoice, the dispatch or the collection cannot post (OFFICIAL_RATE_STALE, IGTF_SUBJECT_UNCLASSIFIED and the other gaps)", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CounterSaleProblem" }, { "required": [ "error", "missing" ], "properties": { "error": { "type": "string", "enum": [ "accounting_configuration_incomplete" ] }, "missing": { "type": "array", "items": { "type": "object" } } }, "type": "object" } ] } } } }, "500": { "description": "Unexpected, reported: for example a lost race the three attempts did not settle, even one a step wrapped in its own error (its error_code is then that step's), or an approved invoice whose total drifted from its quote (counter_sale_invoice_total_drifted). The till resends with the same key. Naming a Pedido web, reservations_not_adoptable and counter_sale_invoice_total_drifted are integrity failures where nothing committed: resending the same answer comes back, so a till treats them as definite.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CounterSaleProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/pos/refunds": { "get": { "tags": [ "Backoffice - Sales - Counter Sales" ], "summary": "List a Caja's pending counter sale refunds", "description": "The pending refunds of one Caja (MER-4979): one page of the electronic «Reembolso de anulación» refunds of the company's voided Venta de mostrador sales charged at that Caja that still wait for their external reference, oldest first (voided_at, then payment_index, then id, all ascending), with each one's age in seconds by the server's clock. A cash refund is never listed, nor a confirmed one. An unknown Caja and another company's answer an empty page, never 404. Blank query values count as absent. Requires backoffice.sales.counter-sales.view; a POS session token reaches it. A plain read with no lock; it never blocks a Turno's close, which never reads it.", "operationId": "searchPendingCounterSaleRefunds", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "description": "Which refunds to list; only pending_confirmation is supported.", "required": true, "schema": { "type": "string", "enum": [ "pending_confirmation" ] } }, { "name": "cash_register_id", "in": "query", "description": "The Caja whose sales' pending refunds to list.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1, "maximum": 1000, "minimum": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "The page", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PendingCounterSaleRefundPage" } } } }, "401": { "description": "Unauthenticated: the auth middleware answers before the controller", "content": { "application/json": { "schema": { "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "403": { "description": "Without backoffice.sales.counter-sales.view, or a caller who does not belong to the company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CounterSaleProblem" } } } }, "404": { "description": "Only the middleware's answer for a tenant the caller or the POS token does not reach", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CounterSaleProblem" } } } }, "422": { "description": "status is missing or not pending_confirmation, cash_register_id is missing or not a UUID, page is outside 1 to 1000, or per_page is outside 1 to 100 (errors names the parameter)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CounterSaleProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/pos/sales/{id}/receipt": { "get": { "tags": [ "Backoffice - Sales - Counter Sales" ], "summary": "Read a counter sale's non-fiscal ticket", "description": "The Ticket no fiscal of a Venta de mostrador of the company (MER-4975, ADR 0219): titled «DOCUMENTO NO FISCAL» with the footer «Sin valor fiscal», it shows the company, the sale code, when it was sold, the Vendedora, the Caja, the lines, the total and its counterpart, the payments with their IGTF and reference, and the buyer only when one was given. It never carries «Factura», the invoice or control number, the fiscal-machine serial, «SENIAT», or VAT totals or breakdown. A voided sale's ticket keeps all of it and adds «ANULADA», when, why, and who voided and authorized it (MER-4979). Line amounts include VAT: a line's unit_price is the item's own price, less its discount, plus its tax, rounded once, so unit_price × quantity can differ from the line total by rounding, and the lines can differ from `total` by per-tax-group rounding; `total` is the charged total. Any holder of backoffice.sales.counter-sales.view in the company reads it, on any Caja and for any Vendedora's sale; a POS session token reaches it. A holder of backoffice.sales.counter-sales.sell without view reads only their own sale, including after its Turno closes. A plain read with no lock.", "operationId": "b14c23e2163245e2d4848b7d04863d28", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "The sale's id.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The ticket", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PosReceipt" } } } }, "401": { "description": "Unauthenticated: the auth middleware answers before the controller", "content": { "application/json": { "schema": { "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "403": { "description": "Without either backoffice.sales.counter-sales.view or backoffice.sales.counter-sales.sell, or a caller who does not belong to the company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CounterSaleProblem" } } } }, "404": { "description": "counter_sale_not_found: no such sale in the company, another Vendedora's sale for a sell-only caller, or another company's; the router's `message` for an id that is not a UUID; or the middleware's answer for a tenant the caller or the POS token does not reach", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CounterSaleProblem" }, { "$ref": "#/components/schemas/PosRouteNotFound" } ] } } } }, "500": { "description": "pos_receipt_source_missing, reported: the sale's sales document, its collection or, for a voided sale, its Anulación cannot be read, which no request causes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CounterSaleProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/pos/sales/{id}/fiscal-identity": { "post": { "tags": [ "Backoffice - Sales - Counter Sales" ], "summary": "Capture the fiscal identity of a counter sale's invoice", "description": "Transcribes onto the sale's Sales Invoice the document the company's Issuance Channel issued for a Venta de mostrador, at completion or later (MER-4975, ADR 0219), with every rule of the Backoffice capture (PUT sales-invoices/{id}/fiscal-identity). The numbers are kept as printed, as there: trimmed, with case, inner spaces and leading zeros kept, 1 to 30 letters, digits, spaces, hyphens, ° or º. Unlike the PUT, which replaces the pair together, an omitted control_number keeps the stored one, as an omitted fiscal_machine_serial keeps the stored serial; null or blank clears either. A fiscal_machine company is never asked for a control number. A control number already held by another non-cancelled invoice or note of the company answers 409. A repeated identical capture writes nothing and answers 204 again. The sale never changes: a refused capture leaves it charged. Any holder of backoffice.sales.counter-sales.sell in the company captures on any of its sales; it reaches only the invoice of a counter sale, by the sale's id. A POS session token reaches it.", "operationId": "9aaaedf26da3db34e6227abef793f49b", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "The sale's id.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "invoice_number" ], "properties": { "issued_in_contingency": { "description": "Optional manual mark on the invoice; omit to preserve the stored mark. False clears it. Never changes the charged sale or its non-fiscal ticket.", "type": "boolean" }, "contingency_reason": { "type": "string", "nullable": true, "maxLength": 40, "enum": [ "power_failure", "internet_outage", "equipment_failure", "unplanned_maintenance", "fiscal_machine_unable", "third_party", "export", "multiple_copies", "other" ] }, "contingency_note": { "description": "Required for other; optional for the listed reasons.", "type": "string", "nullable": true, "maxLength": 500 }, "invoice_number": { "description": "The invoice number as printed. Required: the till records or corrects an identity and never erases it.", "type": "string", "example": "00-001234", "maxLength": 60 }, "control_number": { "description": "The control number as printed, unique among the company's non-cancelled invoices and notes. Omit the key to keep the control number the invoice holds, so correcting only the invoice number never erases it; send null or blank to clear it.", "type": "string", "example": "00-00012345", "nullable": true, "maxLength": 60 }, "fiscal_machine_serial": { "description": "The serial of the fiscal machine that printed the document (ADR 0261), canonicalized as there (whitespace dropped, upper-cased) and never stored as the control number. Omit the key to keep the stored serial; send null or blank to clear it.", "type": "string", "example": "Z1B-0042", "nullable": true, "maxLength": 60 } }, "type": "object" } } } }, "responses": { "204": { "description": "Captured, or already captured identically" }, "401": { "description": "Unauthenticated: the auth middleware answers before the controller", "content": { "application/json": { "schema": { "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "403": { "description": "Without backoffice.sales.counter-sales.sell, or a caller who does not belong to the company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CounterSaleProblem" } } } }, "404": { "description": "counter_sale_not_found: no such sale in the company, the same answer for another company's; the router's `message` for an id that is not a UUID; or the middleware's answer for a tenant the caller or the POS token does not reach", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CounterSaleProblem" }, { "$ref": "#/components/schemas/PosRouteNotFound" } ] } } } }, "409": { "description": "The control number already belongs to another non-cancelled invoice or note of this company (sales_invoice_control_number_already_registered), or a frozen fiscal period declared the invoice (document_in_frozen_fiscal_period, with `fiscal_period`)", "content": { "application/json": { "schema": { "required": [ "title", "status", "detail", "error_code" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer", "example": 409 }, "detail": { "type": "string" }, "error_code": { "type": "string", "example": "sales_invoice_control_number_already_registered", "enum": [ "sales_invoice_control_number_already_registered", "document_in_frozen_fiscal_period" ] }, "existing_code": { "description": "The code of the document, invoice or note, that already holds the control number, or null when a concurrent commit leaves the failure path unable to name it.", "type": "string", "example": "INV00001", "nullable": true }, "existing_kind": { "description": "The kind of the document that already holds the control number: invoices and notes share one control series. Null exactly when existing_code is null.", "type": "string", "example": "regular", "nullable": true, "enum": [ "regular", "opening", "credit_note", "debit_note", "advance" ] }, "errors": { "type": "object", "nullable": true }, "fiscal_period": { "description": "Only on document_in_frozen_fiscal_period: the period whose current Declared Set holds the invoice.", "allOf": [ { "$ref": "#/components/schemas/FrozenFiscalPeriod" } ] } }, "type": "object" } } } }, "422": { "description": "invoice_number is missing, a field is not a string or longer than 60 characters (errors names it); a number or the serial is outside the canonical form (invalid_invoice_number, invalid_control_number, invalid_fiscal_machine_serial); the contingency mark/reason is incomplete (invalid_sales_document_contingency); or the invoice is cancelled (sales_invoice_cannot_be_modified)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CounterSaleProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/pos/sales/lookup": { "get": { "tags": [ "Backoffice - Sales - Counter Sales" ], "summary": "Look up a counter sale by its idempotency key", "description": "Recovers the Venta de mostrador a till charged under an idempotency key when its answer was lost (MER-4974): the same body its 201 answered. A plain read with no lock, so it answers after the Turno closes too. Only the Vendedora who charged it finds it; to anyone else, as for a key never charged, it answers 404 counter_sale_not_found. Requires backoffice.sales.counter-sales.sell; a POS session token reaches it.", "operationId": "ac5ba76cad1632bb831f8c1f2b4c9051", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "idempotency_key", "in": "query", "description": "The key the till charged the sale with: 1 to 100 of A-Z, a-z, 0-9, \".\", \"_\", \":\" or \"-\", compared exactly.", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,100}$", "maxLength": 100 } } ], "responses": { "200": { "description": "The sale", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CounterSale" } } } }, "401": { "description": "Unauthenticated: the auth middleware answers before the controller", "content": { "application/json": { "schema": { "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "403": { "description": "Without backoffice.sales.counter-sales.sell, or a caller who does not belong to the company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CounterSaleProblem" } } } }, "404": { "description": "counter_sale_not_found: no sale of this Vendedora under the key; or the middleware's answer for a tenant the caller or the POS token does not reach", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CounterSaleProblem" } } } }, "422": { "description": "The idempotency_key query parameter is missing or malformed (errors names it)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CounterSaleProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/pos/sales/{id}/refunds/{refundId}/confirm": { "post": { "tags": [ "Backoffice - Sales - Counter Sales" ], "summary": "Confirm a counter sale's electronic refund", "description": "Confirms an electronic «Reembolso de anulación» of a voided Venta de mostrador (MER-4979, ADR 0312) by recording the external reference of the bank or wallet refund: a pending_confirmation refund becomes confirmed, with that reference, when (UTC) and by whom. It locks only that refund's row: no Turno, no sale and no void. It is allowed after the sale's Turno closed and on any later day, and it never blocks closing a Turno. It posts nothing to the ledger, records no Movimiento de caja and changes no treasury position: the void's cancelled Collection already reversed the money. The reference is the confirmation's idempotency key: sending the same reference again, trimmed and case included, answers 200 with the refund as it stands, its original confirmer and time, and changes nothing; another reference answers 409 counter_sale_refund_already_confirmed. A cash refund left the drawer at the void and answers 409 counter_sale_refund_not_pending. Any holder of backoffice.sales.counter-sales.sell in the company confirms a refund of any of its Cajas; a POS session token reaches it.", "operationId": "confirmCounterSaleRefund", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "The voided sale's id.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "refundId", "in": "path", "description": "The id of one of its refunds, as the void answered it.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CounterSaleRefundConfirmRequest" } } } }, "responses": { "200": { "description": "The refund is confirmed: by this request, or already with the same reference, in which case nothing changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CounterSaleRefund" } } } }, "401": { "description": "Unauthenticated: the auth middleware answers before the controller", "content": { "application/json": { "schema": { "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "403": { "description": "Without backoffice.sales.counter-sales.sell, or a caller who does not belong to the company: the middleware answers before the controller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CounterSaleProblem" } } } }, "404": { "description": "counter_sale_refund_not_found: the sale is absent, another company's or never voided, or the refund is unknown or another sale's, all the same answer; the router's `message` for an id that is not a UUID; or the middleware's answer for a tenant the caller or the POS token does not reach", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CounterSaleProblem" }, { "$ref": "#/components/schemas/PosRouteNotFound" } ] } } } }, "409": { "description": "counter_sale_refund_not_pending: a cash refund, which has no reference to confirm; counter_sale_refund_already_confirmed: the refund is confirmed with another reference, which the answer never echoes. Nothing changes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CounterSaleProblem" } } } }, "422": { "description": "Request validation failed (errors names external_reference): missing, blank or longer than 100 characters. Nothing changes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CounterSaleProblem" } } } }, "500": { "description": "Unexpected, reported: a lost race the three attempts did not settle, or a stored refund whose confirmation drifted from its status. Nothing changes; the till may send it again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CounterSaleProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/pos/sales/{id}/void": { "post": { "tags": [ "Backoffice - Sales - Counter Sales" ], "summary": "Void a counter sale of today", "description": "Voids a Venta de mostrador of the company's today («Anulación», MER-4978, ADR 0312 as amended by ADR 0319 and ADR 0320) in one transaction: its dispatch goes back to Pending (stock back by quantity, its cost of sale mirrored, its Reservas restored), its Collection is cancelled (its entry inverted in both books at its own rates, IGTF included, and its invoice's balances restored) and its Sales Invoice is cancelled (its entry reversed, its now Pending dispatch cancelled and its Reservas released with reason cancelled). Stock, Cantidad reservada, average cost, the customer's receivable and each treasury position return to their values before the sale. The sale reads voided in its receipt and in its Turno's list. One refund is recorded per payment the sale froze, in the instrument's currency and IGTF included: a cash payment is refunded at once out of the open Turno of the sale's Caja, which must be open (no Movimiento de caja is recorded: the cancelled collection already lowers the expected cash); any other rail is pending_confirmation until its external reference is recorded with POST pos/sales/{id}/refunds/{refundId}/confirm, and GET pos/refunds lists a Caja's pending ones (MER-4979). Any failure rolls everything back, the consumed authorization included. A holder of backoffice.sales.counter-sales.void voids on their own authority and a token they send is ignored; anyone else presents an Autorización de la dueña granted for this sale and this requester (POST pos/exception-approvals), consumed here once. Who voided and who authorized are answered by user id. A sale with a registered fiscal document is returned with a credit note instead (409). A second void, a retry after a lost answer included, answers 409 counter_sale_already_voided; the till reads the sale's state from its receipt. Requires backoffice.sales.counter-sales.sell; a POS session token reaches it.", "operationId": "voidCounterSale", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "The sale's id.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CounterSaleVoidRequest" } } } }, "responses": { "200": { "description": "The sale was voided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CounterSaleVoid" } } } }, "401": { "description": "Unauthenticated: the auth middleware answers before the controller", "content": { "application/json": { "schema": { "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "403": { "description": "owner_authorization_required: the caller holds neither backoffice.sales.counter-sales.void nor presents a token; owner_authorization_invalid: the token is unknown, expired, already consumed, or of another company, action, sale or requester (the reason is logged, never answered); or, before the controller, the middleware's answer without backoffice.sales.counter-sales.sell or for a caller who does not belong to the company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CounterSaleProblem" } } } }, "404": { "description": "counter_sale_not_found: no such sale in the company, the same answer for another company's; the router's `message` for an id that is not a UUID; or the middleware's answer for a tenant the caller or the POS token does not reach", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CounterSaleProblem" }, { "$ref": "#/components/schemas/PosRouteNotFound" } ] } } } }, "409": { "description": "counter_sale_already_voided; cash_shift_not_open (with cash_register_id): a sale with a cash payment whose Caja has no open Turno; counter_sale_fiscal_document_registered: its invoice has an invoice number, a control number or a fiscal machine serial, so it is returned with a credit note; counter_sale_collection_not_applied: its Collection was cancelled in the Backoffice; counter_sale_invoice_has_live_notes: its invoice has a credit or debit note that is not cancelled; document_in_frozen_fiscal_period (with fiscal_period): a frozen Fiscal Period declared its invoice; remitted_igtf_requires_adjustment: a remittance already paid its IGTF; sales_invoice_has_received_withholding. Nothing changes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CounterSaleProblem" } } } }, "422": { "description": "Request validation failed (errors names reason or authorization_token); counter_sale_void_outside_store_day (with business_day): the sale is of another Día de tienda; or {error: accounting_configuration_incomplete, missing[]} when a reversal cannot post, the accounting period of today closed included. Nothing changes.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CounterSaleProblem" }, { "required": [ "error", "missing" ], "properties": { "error": { "type": "string", "enum": [ "accounting_configuration_incomplete" ] }, "missing": { "type": "array", "items": { "type": "object" } } }, "type": "object" } ] } } } }, "500": { "description": "Unexpected, reported: a lost race the three attempts did not settle, or stored documents that drifted from what the void expects. Nothing changes; the till may send it again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CounterSaleProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/pos/quote": { "post": { "tags": [ "Backoffice - Sales - Counter Sales" ], "summary": "Quote a counter sale", "description": "The Cotización POS (MER-4973, ADR 0311): what a counter sale through the Caja would charge today, stateless. Each line takes its channel price with its Huella v2 (ADR 0272), its Item's «Impuesto de venta por defecto» (ADR 0317) and its Disponible at the Canal's Location; a line no invoice could hold is reported in blocked_by, never refused, and left out of the totals. The totals carry their counterpart at the official document rate of the company's day (ADR 0143), as approving the invoice freezes it. When payments are sent, each previews the debt it settles, the rate of its cash event and its IGTF (ADR 0193), and the settlement says whether they settle the total by the charge's own check; no Treasury Position is read or locked. quote_fingerprint is what the charge compares when it quotes again: a payment reference, the buyer's document and name, the Disponible and the rails are never part of it. Each rail carries settle_amount, the amount that would settle what remains through it, IGTF included, verified by the same check; null when nothing remains or the rail cannot be valued, and never fingerprinted. unidentified_buyer_after_legal_date warns, from 2027-04-19, of an invoice to the Consumidor final whose buyer lacks a name or a document; it never blocks the charge (ADR 0352, MER-5756). Nothing is written and no Consumidor final is provisioned: it answers 200, not 201. A non-null web_order_id quotes a Pedido web this seller holds instead (MER-5432): its frozen lines, Client and document currency, at today's rate and rails, with its online terms apart under web_order. It also requires backoffice.sales.web-orders.claim, before its body is validated. Requires backoffice.sales.counter-sales.sell; a POS session token reaches it.", "operationId": "55f3c12615a6a185ef7e25b1fcc2e882", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PosQuoteRequest" }, { "$ref": "#/components/schemas/WebOrderPosQuoteRequest" } ] } } } }, "responses": { "200": { "description": "The quote", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PosQuote" } } } }, "401": { "description": "Unauthenticated: the auth middleware answers before the controller", "content": { "application/json": { "schema": { "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "403": { "description": "Without backoffice.sales.counter-sales.sell, or a caller who does not belong to the company; or, naming a Pedido web, without backoffice.sales.web-orders.claim", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PosQuoteProblem" } } } }, "404": { "description": "cash_register_not_found: an unknown Caja or another company's; web_order_not_found: unknown, or of another company or Location, the same answer for each; or the middleware's answer for a tenant the caller or the POS token does not reach", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PosQuoteProblem" } } } }, "409": { "description": "Only naming a Pedido web. cash_shift_not_open (with cash_register_id); web_order_already_charged (with charged_sale, order_status, current_version, expires_at and claim); web_order_expired, web_order_not_chargeable, web_order_version_conflict, web_order_not_claimed, web_order_claim_conflict: another seller, cycle or Turno, so another Caja at the same Location (each with order_status, current_version, expires_at and claim); web_order_hold_mismatch: its Reservas no longer match its lines", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderQueueProblem" } } } }, "422": { "description": "Request validation failed; counter_sale_cash_register_not_selling (with reason); counter_sale_item_not_found (with lines); sale_price_line_unit_not_of_item (with field_errors); invalid_counter_buyer, invalid_cedula, invalid_rif or invalid_passport; counter_sale_client_not_found (with client_id); counter_sale_payment_instrument_not_a_rail (with payments); a collection instrument error when an instrument changed meanwhile; invalid_settlement; cash_event_date_in_the_future; client_fiscal_identity_incomplete (with missing only): a Pedido web's Client cannot be invoiced, or it has none; sales_invoice_tax_selection_invalid: a tax it froze is no longer in the catalog; or, without an official rate for a payment's cash event, {error: accounting_configuration_incomplete, missing[]} with OFFICIAL_RATE_STALE or OFFICIAL_RATE_NOT_AVAILABLE, as the charge would refuse it", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PosQuoteProblem" }, { "required": [ "error", "missing" ], "properties": { "error": { "type": "string", "enum": [ "accounting_configuration_incomplete" ] }, "missing": { "type": "array", "items": { "type": "object" } } }, "type": "object" } ] } } } }, "500": { "description": "Unexpected, reported: for example a Canal naming a list its company does not hold, or counter_sale_invoice_total_drifted when a Pedido web's lines no longer total what it froze", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PosQuoteProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/credit-applications": { "post": { "tags": [ "Backoffice - Sales Credit Applications" ], "summary": "Apply a credit note's Customer Credit or a customer advance to an invoice of its client", "description": "Applies units of a credit source to one open regular invoice of the same client and company, to be collected or partially collected (ADR 0215): the Customer Credit an approved Sales Credit Note keeps (source.type credit_note, status with_customer_credit, MER-3277), or a customer advance, a collection of kind advance still applied with a balance (source.type collection, MER-3279; never «saldo a favor»). The units, in the source's currency, derive the debt they settle at the Rate Snapshot of the application date by the cash-event rule: today takes the official rate known now (a stale one answers the readiness envelope with OFFICIAL_RATE_STALE), an earlier date the rate of its value date (OFFICIAL_RATE_NOT_AVAILABLE when none), a later one is refused (cash_event_date_in_the_future); money kept in both books converts nothing. The date may not precede the note's emission, or the day the advance was collected. Within one cent of the invoice's open balance the debt settles it in full with the cents as a rounding difference; beyond it, 422 application_exceeds_open_balance. The invoice gives up the debt proportionally in its three books (no collection event: a note's application is not a collection, and an advance's counts as collected in the invoice's breakdown), the source its proportional Carrying Amount (a note turning applied when nothing is left, an advance staying applied at a zero balance), and each book's differences post by leg and cause on the application's entry (sales_credit.applied), linked to the application: a note's receivable or the advance's customer_advances is debited on the account and center it was posted on, and the invoice's receivable credited; revenue is never touched. Applying several invoices means one request per invoice with distinct ids; the source is locked, so a request whose units exceed what it still holds answers 409 credit_balance_exceeded, naming what is available. The client generates the UUID id: resending it with the same source type and id, target, units and date answers 200 with the application as stored, without writes; with anything else, or an id another company holds, 409 sales_credit_application_id_conflict. While an application is live its note cannot be cancelled, nor its advance (409 advance_has_applications). Requires backoffice.sales.collections.apply-credit.", "operationId": "applyCustomerCredit", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "id", "source", "target", "source_units", "date" ], "properties": { "id": { "type": "string", "format": "uuid" }, "source": { "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "credit_note", "collection" ] }, "id": { "description": "A Sales Credit Note of the company (credit_note; a missing or foreign one answers 422 sales_credit_note_not_found), or a customer advance (collection; a missing or foreign one answers 422 collection_not_found, a settlement collection 422 application_source_not_open).", "type": "string", "format": "uuid" } }, "type": "object" }, "target": { "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "sales_invoice" ] }, "id": { "description": "A sales invoice of the company; a missing or foreign one, or a credit note, answers 422 sales_invoice_not_found.", "type": "string", "format": "uuid" } }, "type": "object" }, "source_units": { "description": "Greater than zero, at most two decimals, in the source's currency.", "type": "string", "pattern": "^(?!0+(?:\\.0{1,2})?$)\\d{1,13}(?:\\.\\d{1,2})?$", "example": "80.00" }, "date": { "description": "Y-m-d, on or after the note's emission or the advance's collection, and no later than the company's today.", "type": "string", "format": "date", "example": "2026-10-03" } }, "type": "object" } } } }, "responses": { "201": { "description": "Applied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesCreditApplication" } } } }, "200": { "description": "The same id was already applied with the same terms; nothing was written", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesCreditApplication" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks backoffice.sales.collections.apply-credit" }, "409": { "description": "credit_balance_exceeded: the units exceed what the note or the advance holds now, or it already gave up all of it; sales_credit_application_id_conflict: the id is used with other terms, another source type, or by another company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesCreditApplicationProblem" } } } }, "422": { "description": "Validation (errors); sales_credit_note_not_found, collection_not_found or sales_invoice_not_found for a body reference; application_source_not_open (a draft or cancelled note, a settlement collection or a cancelled advance); application_target_not_open (an opening, a debit note, or a draft, cancelled or fully collected invoice); application_counterparty_mismatch (another client's invoice); application_date_precedes_credit_note; application_date_precedes_advance; application_exceeds_open_balance; application_settles_nothing; cash_event_date_in_the_future; unsupported_cash_event_currency. A missing accounting configuration answers the readiness envelope instead.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/SalesCreditApplicationProblem" }, { "$ref": "#/components/schemas/SalesCreditApplicationAccountingConfigurationError" } ] } } } }, "500": { "description": "A broken stored invariant (an advance without its posted advance_received entry answers sales_collection_posting_unavailable) or a failed write; the transaction rolls back.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesCreditApplicationProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/credit-applications/preview": { "get": { "tags": [ "Backoffice - Sales Credit Applications" ], "summary": "Preview applying a credit note's Customer Credit or a customer advance to an invoice", "description": "What applying the source's units to the invoice on the date would record (MER-3277, MER-3279), by the same eligibility, Rate Snapshot rule, settlement and accounting readiness as applying, with nothing locked or written: it refuses exactly what applying would, a readiness refusal naming the source. Without source_units it proposes the lesser of what the note or the advance holds and the units that settle the invoice in full at that snapshot. Requires backoffice.sales.collections.apply-credit.", "operationId": "previewSalesCreditApplication", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "source_type", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "credit_note", "collection" ] } }, { "name": "source_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "target_type", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "sales_invoice" ] } }, { "name": "target_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "source_units", "in": "query", "description": "Greater than zero, at most two decimals, in the source's currency; omitted, the preview proposes them.", "required": false, "schema": { "type": "string", "pattern": "^(?!0+(?:\\.0{1,2})?$)\\d{1,13}(?:\\.\\d{1,2})?$" } }, { "name": "date", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "What applying would record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesCreditApplicationPreview" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks backoffice.sales.collections.apply-credit" }, "409": { "description": "credit_balance_exceeded: the units exceed what the note or the advance holds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesCreditApplicationProblem" } } } }, "422": { "description": "The refusals of applying: validation (errors), sales_credit_note_not_found, collection_not_found, sales_invoice_not_found, application_source_not_open, application_target_not_open, application_counterparty_mismatch, application_date_precedes_credit_note, application_date_precedes_advance, application_exceeds_open_balance, application_settles_nothing, cash_event_date_in_the_future, unsupported_cash_event_currency, or the readiness envelope.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/SalesCreditApplicationProblem" }, { "$ref": "#/components/schemas/SalesCreditApplicationAccountingConfigurationError" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/credit-applications/{id}/revert": { "post": { "tags": [ "Backoffice - Sales Credit Applications" ], "summary": "Unapply a credit note's Customer Credit or a customer advance from an invoice", "description": "Unapplies a credit application (MER-3277, MER-3279): the invoice and its source get back exactly what it relieved, never valued again (a note keeps its Customer Credit again, an advance its balance, so it can be cancelled once nothing of it is applied), and the entry is inverted line by line in both books by sales_credit.reverted, dated at the company's today and linked by reverses_transaction_id. Repeating it answers 200 with the application as it stands, without writes. The application a note's approval recorded on its origin reverts only with its note (422 application_not_revertible). Requires backoffice.sales.collections.apply-credit.", "operationId": "revertSalesCreditApplication", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Unapplied, now or before", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesCreditApplication" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks backoffice.sales.collections.apply-credit" }, "404": { "description": "sales_credit_application_not_found: no application of the company has that id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesCreditApplicationProblem" } } } }, "422": { "description": "application_not_revertible: it was recorded at its note's approval", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesCreditApplicationProblem" } } } }, "500": { "description": "A broken stored invariant (sales_credit_application_integrity_error, also when its note or advance cannot be read; sales_credit_application_posted_transaction_missing) or a failed write; the transaction rolls back.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesCreditApplicationProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/credit-notes/{id}/accounting-readiness": { "get": { "tags": [ "Backoffice - Sales Credit Notes" ], "summary": "Get the accounting readiness of a sales credit note", "description": "Whether approving the note could post its sales_credit_note.approved entry now (MER-3336), in the shape of every readiness endpoint. A draft (to_be_approved) is valued as its approval values it and checked by the approval's own readiness: the sales_returns Posting Account, the realized exchange role its application to the origin would round on, the origin invoice's receivable account and center, each taxed group's account and center, each line's center, the parallel-currency flow and, last, the closed period of the note's emission date. A draft on an advance invoice (MER-4264) is checked for its own `sales_advance_invoice_credit_note.approved` entry instead: the customer_advances Posting Account (CUSTOMER_ADVANCES_ACCOUNT_MISSING), each taxed group's account and center, the parallel-currency flow and the period, never sales_returns, the receivable or the line centers. The check runs on plain reads of the origin that lock and write nothing, so it is a snapshot: approval values the note again under the origin's lock and stays the authority. A note past its draft (with_customer_credit, applied, cancelled) has nothing left to approve and reads ready with no gaps. warnings is always empty for notes. A draft that cannot be valued is refused with the 422 its approval would answer. Requires `backoffice.sales.credit-notes.view`.", "operationId": "showSalesCreditNoteAccountingReadiness", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Accounting readiness snapshot; ready is true exactly when missing is empty", "content": { "application/json": { "schema": { "required": [ "ready", "missing", "warnings" ], "properties": { "ready": { "type": "boolean" }, "missing": { "type": "array", "items": { "required": [ "reason_code", "subject_type", "subject_id", "human_message", "details" ], "properties": { "reason_code": { "type": "string", "example": "SALES_POSTING_ACCOUNT_MISSING" }, "subject_type": { "type": "string", "example": "company" }, "subject_id": { "type": "string" }, "human_message": { "type": "string" }, "details": { "type": "array", "items": { "type": "string" }, "example": [ "sales_returns" ] } }, "type": "object" } }, "warnings": { "$ref": "#/components/schemas/AccountingReadinessWarnings" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks backoffice.sales.credit-notes.view, or is not a member of the tenant" }, "404": { "description": "sales_credit_note_not_found: the note does not exist or belongs to another company, also for an invoice or a debit note id. An id that is not a UUID is answered by the router before the controller with a `message` body.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/SalesCreditApplicationProblem" }, { "required": [ "message" ], "properties": { "message": { "type": "string" } }, "type": "object" } ] } } } }, "422": { "description": "The draft cannot be valued, so its approval would refuse it for a reason that is not a configuration gap: its origin can no longer be credited (sales_credit_note_origin_not_found, _is_opening, _not_approved, _cancelled, _is_a_note, _without_valuation, or advance_invoice_not_pending); a note on an advance invoice is not total (advance_invoice_credit_must_be_total); a unit return is worth nothing left (sales_credit_note_line_without_amount) or a line's tax group was already credited in full (sales_credit_note_group_without_value); approved credits beyond what the origin line invoiced (line_credit_cap_*); a group credit is above what remains of it (tax_group_credit_exceeds_remainder); a frozen group has no parallel amounts (sales_invoice_tax_summary_not_valued); or a line is above what its origin line still has (the SalesCreditNoteLineCapExceeded body). The same codes the approval answers.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/SalesCreditApplicationProblem" }, { "$ref": "#/components/schemas/SalesCreditNoteLineCapExceeded" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/credit-notes/{id}/approve": { "post": { "tags": [ "Backoffice - Sales Credit Notes" ], "summary": "Approve a draft sales credit note", "description": "Approves a draft Sales Credit Note in one transaction, locking its origin before the note. An Opening Document origin (MER-4639) is valued as an exact share of its frozen totals (ADR 0303): Opening Rebate lines have no origin-line caps, and a note whose gross no longer fits the opening remainder under lock answers 422 sales_credit_note_exceeds_opening_total with `available` and writes nothing. On a regular or advance invoice origin, its lines are valued again at the caps its origin's approved notes leave, and each tax group as the exact share of the origin's frozen valuation; the note that leaves a group with nothing to credit takes its exact remainder. The note applies to the origin's open balance up to what the origin owes, through a Credit Application; the origin's status follows its balance, and what is left stays as the note's Customer Credit (status with_customer_credit, or applied when nothing is left). The approval posts the sales_credit_note.approved entry: returns on the sales_returns account, the tax, the receivable, and any rounding. When a received VAT withholding relieved the origin, the same transaction reviews each standing supported withholding on it (MER-3697, rule 881): one that still withholds more of the origin than the VAT in bolívars the approved notes leave allows, at the percentage it withheld, is flagged `review.state: pending` with this note; the answer carries no withholding state, so refetch `GET fiscal/received-withholdings?sales_invoice_id={origin}` after approving. When the company cannot post it, the approval answers 422 accounting_configuration_incomplete naming each missing configuration, such as SALES_POSTING_ACCOUNT_MISSING with details [sales_returns], and writes nothing. A note on an advance invoice whose service is not rendered (MER-4264) locks the advance invoice, then the note, then the advance invoice's Advance: it is valued at the whole advance invoice, applies nothing and keeps no Customer Credit (status applied, applied_amount and customer_credit 0.00, credit_application_id null, its three balances null in storage), gives the advance invoice's VAT back to its Advance in every book, releases the Advance and marks the advance invoice credited. It posts `sales_advance_invoice_credit_note.approved` on the note's own date instead: each tax group's VAT debited to its tax account and the sum credited to customer_advances, at the advance invoice's frozen valuation. Its readiness asks for customer_advances (CUSTOMER_ADVANCES_ACCOUNT_MISSING), the tax account and center, the parallel-currency flow and the period of the note's date, never sales_returns or the receivable. An advance invoice applied by a balance invoice, credited or cancelled while the note waited answers 422 advance_invoice_not_pending, a note no longer total 422 advance_invoice_credit_must_be_total, and a note dated in a frozen fiscal period 422 document_in_frozen_fiscal_period with `fiscal_period`, before anything is locked. A note with Unit Return lines on a regular invoice (MER-5687, ADR 0365) locks the open dispatch of its sale after the note, the order's dispatch for an invoice from an order, and judges it line by line at the factor the dispatch froze: one that covers everything still open ends the dispatch in the same transaction, a pending one cancelled and a partial one closed short, its Reservas released and nothing posted, and that note can no longer be cancelled; one that reaches open units without covering them all, or leaves units of the order uninvoiced, answers 409 sales_credit_note_leaves_units_open with `dispatch_id` and `dispatch_code`, writes nothing and stays a draft. A note that reaches no open unit approves as before. It takes no body; a replay answers 422 sales_credit_note_cannot_be_modified. Requires `backoffice.sales.credit-notes.approve`. Approving a Sales Credit Note whose Unit Returns reach shipped units creates, in the same transaction, one Return Entry: an Inventory Entry of origin `sales_credit_note`, pending, with one line per dispatch line. The approval moves no stock and posts nothing for it (MER-2942). A return takes open units first, then shipped ones. A line never asks for more than its dispatch line has left.", "operationId": "approveSalesCreditNote", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Credit note approved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesCreditNoteApproved" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks backoffice.sales.credit-notes.approve" }, "404": { "description": "sales_credit_note_not_found, also for an invoice id", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "detail": { "type": "string" }, "error_code": { "type": "string", "enum": [ "sales_credit_note_not_found" ] } }, "type": "object" } } } }, "409": { "description": "The Unit Return reaches units its sale's dispatch still owes and does not cover them all (sales_credit_note_leaves_units_open); nothing is written, and the note can be approved once a person ends the dispatch.", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "detail": { "type": "string" }, "error_code": { "type": "string", "enum": [ "sales_credit_note_leaves_units_open" ] }, "errors": { "type": "object", "nullable": true }, "dispatch_id": { "description": "The dispatch still open.", "type": "string", "format": "uuid" }, "dispatch_code": { "description": "Its code, as the person reads it.", "type": "string", "example": "ID2600034" } }, "type": "object" } } } }, "422": { "description": "The note is not a draft (sales_credit_note_cannot_be_modified); its origin can no longer be credited (sales_credit_note_origin_not_found, _not_approved, _cancelled, _is_a_note, _without_valuation, or advance_invoice_not_pending with advance_invoice_id and advance_invoice_status); an Opening Document remainder the note no longer fits (sales_credit_note_exceeds_opening_total with `available`); a note on an advance invoice is not total (advance_invoice_credit_must_be_total) or is dated in a frozen fiscal period (document_in_frozen_fiscal_period, with `fiscal_period`); a line is above what its origin line still has (the SalesCreditNoteLineCapExceeded body), a unit return is worth nothing left (sales_credit_note_line_without_amount), or a line's tax group was already credited in full by the approved notes, so the note would credit nothing (sales_credit_note_group_without_value); a group credit is above what remains of it (tax_group_credit_exceeds_remainder); a frozen group has no parallel amounts (sales_invoice_tax_summary_not_valued); the control line values to 0.00 in both books (document_values_to_zero_in_both_books); or the entry cannot post, answered as {error: accounting_configuration_incomplete, missing: [{reason_code, subject_type, subject_id, human_message, details}]}.", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string" }, "error_code": { "type": "string", "example": "sales_credit_note_cannot_be_modified", "nullable": true }, "advance_invoice_id": { "description": "Only on advance_invoice_not_pending: the advance invoice the note credits.", "type": "string", "format": "uuid" }, "advance_invoice_status": { "description": "Only on advance_invoice_not_pending: what the advance invoice is now.", "type": "string", "enum": [ "applied", "credited", "cancelled" ] }, "fiscal_period": { "description": "Only on document_in_frozen_fiscal_period: the frozen period the note's emission date falls in.", "allOf": [ { "$ref": "#/components/schemas/FrozenFiscalPeriod" } ] }, "available": { "description": "Only on sales_credit_note_exceeds_opening_total: the opening remainder still available in the document currency.", "type": "string", "example": "58.00" }, "error": { "description": "Only on a globally rendered refusal: line_credit_cap_exceeded or accounting_configuration_incomplete.", "type": "string" }, "missing": { "description": "Only on accounting_configuration_incomplete.", "type": "array", "items": { "type": "object" } } }, "type": "object" } } } }, "500": { "description": "The entry could not be persisted, or a broken invariant" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/credit-notes/{id}/cancel": { "post": { "tags": [ "Backoffice - Sales Credit Notes" ], "summary": "Cancel a sales credit note", "description": "Cancels a Sales Credit Note in one transaction, locking its origin invoice, then the note, then its active Credit Applications. A draft is cancelled without an entry. An approved note restores its origin exactly from each Credit Application, marks each one reverted, gets back what it gave up, and posts `sales_credit_note.cancelled`: the line-by-line inversion of its `sales_credit_note.approved` entry, rounding included, dated the company's today and linked to the note. A note whose credit relieved another invoice, or whose Customer Credit is applied through a live Credit Application (MER-3277), answers 409 `sales_credit_note_credit_used_elsewhere` and writes nothing; once each such application is unapplied, the note cancels. A note whose approval ended a dispatch (MER-5687, ADR 0365) answers 409 `sales_credit_note_ended_its_dispatch` with `dispatch_id` and writes nothing: that dispatch cannot be reopened, so a sale that stands takes a new invoice. Cancelling again answers 200 and writes nothing. A note the current Declared Set of a Fiscal Period in review or closed holds answers 409 `document_in_frozen_fiscal_period` before anything is locked, naming the period in `fiscal_period` (MER-3837). A note on an advance invoice (MER-4264) applied nothing: once approved it locks the advance invoice's Advance after the note, takes back the VAT it gave it in every book, reserves the Advance for the advance invoice again, marks the advance invoice advance_pending and posts `sales_advance_invoice_credit_note.cancelled`, the inversion of its approved entry, dated the company's today. An Advance applied, refunded, invoiced again or cancelled since answers 409 `advance_used_since_credit_note` with advance_collection_id and advance_invoice_id and writes nothing. Such a note declared in, or dated in, a frozen fiscal period answers 422 `document_in_frozen_fiscal_period` instead of 409. Requires `backoffice.sales.credit-notes.cancel`. A note cancels while its Return Entry has received nothing, and the entry is cancelled with it. Once anything was received the note answers 409 `sales_credit_note_units_received` with `inventory_entry_id` and writes nothing (MER-2942).", "operationId": "cancelSalesCreditNote", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Credit note cancelled, or already cancelled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesCreditNoteCancelled" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks backoffice.sales.credit-notes.cancel" }, "404": { "description": "sales_credit_note_not_found, also for an invoice id", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "detail": { "type": "string" }, "error_code": { "type": "string", "enum": [ "sales_credit_note_not_found" ] } }, "type": "object" } } } }, "409": { "description": "The note's credit relieved an invoice other than its origin (sales_credit_note_credit_used_elsewhere), its approval ended a dispatch (sales_credit_note_ended_its_dispatch, with dispatch_id), the Advance of the advance invoice it credits was used since (advance_used_since_credit_note, with advance_collection_id and advance_invoice_id), or a frozen fiscal period declared it (document_in_frozen_fiscal_period, with `fiscal_period`); nothing is written.", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "detail": { "type": "string" }, "error_code": { "type": "string", "enum": [ "sales_credit_note_credit_used_elsewhere", "sales_credit_note_ended_its_dispatch", "sales_credit_note_units_received", "advance_used_since_credit_note", "document_in_frozen_fiscal_period" ] }, "dispatch_id": { "description": "Only on sales_credit_note_ended_its_dispatch: the dispatch the approval ended.", "type": "string", "format": "uuid" }, "inventory_entry_id": { "description": "Only on sales_credit_note_units_received: the Return Entry that received the goods.", "type": "string", "format": "uuid" }, "advance_collection_id": { "description": "Only on advance_used_since_credit_note: the Advance the note gave its VAT back to.", "type": "string", "format": "uuid" }, "advance_invoice_id": { "description": "Only on advance_used_since_credit_note: the advance invoice the note credits.", "type": "string", "format": "uuid" }, "errors": { "type": "object", "nullable": true }, "fiscal_period": { "description": "Only on document_in_frozen_fiscal_period: the period whose current Declared Set holds the document.", "allOf": [ { "$ref": "#/components/schemas/FrozenFiscalPeriod" } ] } }, "type": "object" } } } }, "422": { "description": "A note on an advance invoice declared in, or dated in, a frozen fiscal period (document_in_frozen_fiscal_period, with `fiscal_period`, MER-4264); nothing is written.", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string" }, "error_code": { "type": "string", "enum": [ "document_in_frozen_fiscal_period" ] }, "errors": { "type": "object", "nullable": true }, "fiscal_period": { "$ref": "#/components/schemas/FrozenFiscalPeriod" } }, "type": "object" } } } }, "500": { "description": "The approved entry is missing (sales_credit_note_posted_transaction_missing), the reversal could not be persisted, or a broken invariant" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/credit-notes/{id}/credit-applications": { "get": { "tags": [ "Backoffice - Sales Credit Notes" ], "summary": "List the applications of a credit note", "description": "Every application of the note, live and reverted, by date then the order they were recorded (MER-3277): the one its approval recorded on its origin (applied_at_approval, dated at the note's emission) and those of its Customer Credit, each as applying it answered. A note applies to a bounded number of invoices, so the list is not paginated. Requires backoffice.sales.credit-notes.view.", "operationId": "listSalesCreditNoteCreditApplications", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The note's applications, empty when it has none", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesCreditApplicationList" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks backoffice.sales.credit-notes.view" }, "404": { "description": "sales_credit_note_not_found: the note does not exist or belongs to another company, also for an invoice id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesCreditApplicationProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/credit-notes/{id}/fiscal-identity": { "put": { "tags": [ "Backoffice - Sales Credit Notes" ], "summary": "Capture or correct a sales credit note's fiscal identity", "description": "Records the note's own invoice number and control number as printed on its paper, in every status except cancelled. Both are kept as printed, like an invoice's (ADR 0380): trimmed, with case, inner spaces and leading zeros kept, 1 to 30 letters, digits, spaces, hyphens, ° or º. The control number shares the company's series with every invoice and note, so one another non-cancelled document holds, compared without whitespace or case (º counts as O), answers 409 naming its code and kind. A note the current Declared Set of a Fiscal Period in review or closed holds answers 409 document_in_frozen_fiscal_period first, naming the period in `fiscal_period` (MER-3837). Requires `backoffice.sales.credit-notes.approve`.", "operationId": "captureSalesCreditNoteFiscalIdentity", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "issued_in_contingency": { "description": "Mark the document as issued in contingency; omitted preserves the stored mark.", "type": "boolean" }, "contingency_reason": { "type": "string", "nullable": true, "enum": [ "power_failure", "internet_outage", "equipment_failure", "unplanned_maintenance", "fiscal_machine_unable", "third_party", "export", "multiple_copies", "other" ] }, "contingency_note": { "description": "Required for other cause.", "type": "string", "nullable": true, "maxLength": 500 }, "invoice_number": { "description": "Blank means absent.", "type": "string", "example": "00-000045", "nullable": true, "maxLength": 60 }, "fiscal_machine_serial": { "description": "Serial printed by the fiscal machine, separate from the control number. Omitted keeps the stored serial; null or blank clears it.", "type": "string", "nullable": true, "maxLength": 60 }, "control_number": { "type": "string", "example": "00-00012346", "nullable": true, "maxLength": 60 } }, "type": "object" } } } }, "responses": { "200": { "description": "Fiscal identity captured" }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks backoffice.sales.credit-notes.approve" }, "404": { "description": "sales_credit_note_not_found" }, "409": { "description": "sales_invoice_control_number_already_registered, or document_in_frozen_fiscal_period when a frozen fiscal period declared the note", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/SalesDocumentControlNumberConflict" }, { "$ref": "#/components/schemas/DocumentInFrozenFiscalPeriodProblem" } ] } } } }, "422": { "description": "sales_credit_note_cannot_be_modified for a cancelled note, invalid_invoice_number, invalid_control_number or invalid_fiscal_machine_serial, or a validation error", "content": { "application/json": { "schema": { "properties": { "error_code": { "type": "string", "example": "invalid_control_number", "nullable": true }, "detail": { "type": "string" }, "errors": { "type": "object", "nullable": true } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/credit-notes/{id}": { "get": { "tags": [ "Backoffice - Sales Credit Notes" ], "summary": "Show a sales credit note", "description": "The detail of a Sales Credit Note: the invoice detail's header, valuation and fiscal-identity keys, plus its origin, reason and lines. While it awaits approval its totals are a preview and its three open balances read 0.00. Once approved, its lines, header and tax_summaries are the approved valuation (each group the exact share of the origin's frozen group), and balance, functional_balance and reporting_balance are the Customer Credit it keeps; once cancelled they read its full valuation again and it keeps none. The origin_* keys describe the invoice it affects (MER-3178). A note on an advance invoice (origin_kind advance, MER-4264) is approved applied, keeps no Customer Credit and its three balances read 0.00. An invoice id answers 404. Requires `backoffice.sales.credit-notes.view`.", "operationId": "showSalesCreditNote", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The credit note", "content": { "application/json": { "schema": { "required": [ "id", "code", "kind", "status", "origin_sales_invoice_id", "origin_code", "origin_invoice_number", "origin_control_number", "origin_emission_date", "origin_total", "origin_kind", "customer_id", "customer_name", "payment_term", "emission_date", "accounting_center_id", "accounting_account_receivable_id", "location_id", "reason", "reason_label", "observations", "subtotal", "discount", "taxes", "total", "balance", "currency", "invoice_number", "control_number", "issuance_channel", "fiscal_machine_serial", "client_fiscal_snapshot", "company_id", "lines", "tax_summaries", "return_entry" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string", "example": "NC2600001" }, "kind": { "type": "string", "enum": [ "credit_note" ] }, "status": { "description": "with_customer_credit keeps part or all of the note as Customer Credit; applied applied it in full; cancelled was cancelled, and its balances read its full valuation again, never as Customer Credit.", "type": "string", "example": "to_be_approved", "enum": [ "to_be_approved", "with_customer_credit", "applied", "cancelled" ] }, "origin_sales_invoice_id": { "type": "string", "format": "uuid" }, "origin_code": { "type": "string", "example": "INV2600007", "nullable": true }, "origin_invoice_number": { "description": "The affected document's invoice number (MER-3178); null when it was never captured or the origin cannot be read.", "type": "string", "example": "00000123", "nullable": true }, "origin_control_number": { "description": "The affected document's control number; null when it was never captured or the origin cannot be read.", "type": "string", "example": "00-000456", "nullable": true }, "origin_emission_date": { "description": "The affected document's emission date; null only when the origin cannot be read.", "type": "string", "format": "date", "example": "2026-09-01", "nullable": true }, "origin_total": { "description": "Total of the affected invoice in its document currency; null if unreadable.", "type": "string", "example": "116.00", "nullable": true }, "origin_kind": { "description": "The affected document's kind (MER-4264): advance for a note crediting an advance invoice; null only when the origin cannot be read.", "type": "string", "example": "regular", "nullable": true, "enum": [ "regular", "advance", null ] }, "customer_id": { "type": "string", "format": "uuid" }, "customer_name": { "type": "string", "nullable": true }, "payment_term": { "type": "string", "example": "thirty_days", "enum": [ "cash", "five_days", "seven_days", "fifteen_days", "thirty_days" ] }, "emission_date": { "type": "string", "format": "date" }, "accounting_center_id": { "type": "string", "format": "uuid" }, "accounting_account_receivable_id": { "type": "string", "format": "uuid" }, "location_id": { "type": "string", "format": "uuid", "nullable": true }, "reason": { "type": "string", "enum": [ "return", "discount", "price_correction", "quantity_correction", "other" ] }, "reason_label": { "type": "string", "example": "Devolución" }, "observations": { "type": "string", "nullable": true }, "subtotal": { "type": "string", "example": "20.00" }, "discount": { "type": "string", "example": "0.00" }, "taxes": { "type": "string", "example": "3.20" }, "total": { "type": "string", "example": "23.20" }, "balance": { "description": "The Customer Credit the approved note keeps in its currency; 0.00 while it awaits approval. A cancelled note holds no Customer Credit: its balance reads its full valuation again.", "type": "string", "example": "0.00" }, "currency": { "type": "string", "example": "USD" }, "functional_rate": { "type": "string" }, "reporting_rate": { "type": "string" }, "rate_rule": { "type": "string" }, "rate_value_date": { "type": "string", "format": "date" }, "functional_total": { "type": "string" }, "reporting_total": { "type": "string" }, "functional_balance": { "type": "string", "example": "0.00" }, "reporting_balance": { "type": "string", "example": "0.00" }, "invoice_number": { "type": "string", "nullable": true }, "control_number": { "type": "string", "nullable": true }, "issuance_channel": { "type": "string", "nullable": true }, "issuance_channel_mismatch": { "description": "Nonblocking warning: recorded note/origin channels differ, except a fiscal_machine_unable contingency, or a free_form origin when the note is dated from the PA SNAT/2026/00093 effective date (2027-04-19). False when either channel is unknown.", "type": "boolean" }, "issued_in_contingency": { "type": "boolean" }, "contingency_reason": { "type": "string", "nullable": true }, "contingency_note": { "type": "string", "nullable": true }, "contingency_reported_on": { "type": "string", "format": "date", "nullable": true }, "fiscal_machine_serial": { "description": "Always null: notes capture no fiscal machine serial yet (MER-4972).", "type": "string", "nullable": true }, "client_fiscal_snapshot": { "type": "object", "nullable": true }, "company_id": { "type": "string", "format": "uuid" }, "return_entry": { "description": "The Return Entry its approval created (MER-2942): the Inventory Entry its shipped units come back through. Null when its Unit Returns reached no shipped unit, on a note with none, and on a note approved before this rule.", "required": [ "id", "code", "status" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string", "example": "IE2600004" }, "status": { "description": "The entry's status: closed_short once its units not received will not come back (R6, ADR 0379).", "type": "string", "enum": [ "pending", "partial", "completed", "closed_short", "cancelled" ] } }, "type": "object", "nullable": true }, "lines": { "type": "array", "items": { "required": [ "id", "origin_sales_invoice_item_id", "line_type", "units", "amount", "category_id", "item_id", "item_name", "unit_id", "tax_id", "tax_percentage", "tax_kind", "accounting_center_id", "accounting_account_id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "origin_sales_invoice_item_id": { "type": "string", "format": "uuid" }, "line_type": { "type": "string", "enum": [ "unit_return", "amount_rebate" ] }, "units": { "description": "Null for an amount_rebate.", "type": "string", "example": "2.0000", "nullable": true }, "amount": { "type": "string", "example": "20.00" }, "category_id": { "type": "string", "format": "uuid" }, "item_id": { "type": "string", "format": "uuid" }, "item_name": { "type": "string" }, "unit_id": { "type": "string", "format": "uuid" }, "tax_id": { "type": "string", "format": "uuid" }, "tax_percentage": { "type": "string", "example": "16.00" }, "tax_kind": { "type": "string" }, "accounting_center_id": { "type": "string", "format": "uuid" }, "accounting_account_id": { "type": "string", "format": "uuid" } }, "type": "object" } }, "tax_summaries": { "description": "Empty until the note is approved; then one per tax group, the approved valuation.", "type": "array", "items": { "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks backoffice.sales.credit-notes.view" }, "404": { "description": "sales_credit_note_not_found, also for an invoice id" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Backoffice - Sales Credit Notes" ], "summary": "Edit a draft sales credit note", "description": "Replaces the date, reason, observations and lines of a credit note awaiting approval, valued again against its origin, which cannot change: the header is inherited from the origin again, and an origin cancelled since registration refuses the edit (sales_credit_note_origin_cancelled). A note past its draft answers 422 sales_credit_note_cannot_be_modified. Omitting both invoice_number and control_number keeps the stored ones; sending either replaces the pair, and an explicit null clears it. The rules of the lines, the caps and the control-number conflict are those of registration: a note on an advance invoice stays total (422 advance_invoice_credit_must_be_total), and one whose advance invoice was applied, credited or cancelled since answers 422 advance_invoice_not_pending (MER-4264). The note may keep its own line ids; a line id that a line of any other document already holds answers 409 sales_credit_note_line_id_conflict, which names only the id sent. Requires `backoffice.sales.credit-notes.create`.", "operationId": "updateSalesCreditNote", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "emission_date", "reason", "lines" ], "properties": { "emission_date": { "description": "On or after the origin's emission date.", "type": "string", "format": "date", "example": "2026-09-29" }, "reason": { "type": "string", "example": "discount", "enum": [ "return", "discount", "price_correction", "quantity_correction", "other" ] }, "observations": { "type": "string", "nullable": true }, "invoice_number": { "description": "Kept as printed; see the registration endpoint.", "type": "string", "nullable": true, "maxLength": 60 }, "control_number": { "description": "Kept as printed; unique among the company's non-cancelled invoices and notes, compared without whitespace or case (º counts as O).", "type": "string", "nullable": true, "maxLength": 60 }, "lines": { "description": "Line ids and origin lines are each distinct.", "type": "array", "items": { "$ref": "#/components/schemas/SalesCreditNoteLineInput" }, "minItems": 1 } }, "type": "object" } } } }, "responses": { "200": { "description": "Credit note edited" }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks backoffice.sales.credit-notes.create" }, "404": { "description": "sales_credit_note_not_found" }, "409": { "description": "sales_credit_note_line_id_conflict: a line id is already used by a line of another document; or sales_invoice_control_number_already_registered, which also carries existing_code and existing_kind (see SalesDocumentControlNumberConflict)", "content": { "application/json": { "schema": { "required": [ "title", "status", "detail", "error_code" ], "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "detail": { "type": "string" }, "error_code": { "type": "string", "enum": [ "sales_credit_note_line_id_conflict", "sales_invoice_control_number_already_registered" ] }, "existing_code": { "description": "Only on sales_invoice_control_number_already_registered: the code of the invoice or note that holds the control number, or null when it cannot be named.", "type": "string", "example": "INV2600007", "nullable": true }, "existing_kind": { "description": "Only on sales_invoice_control_number_already_registered: the kind of that document, null exactly when existing_code is null.", "type": "string", "nullable": true, "enum": [ "regular", "opening", "credit_note", "debit_note", "advance" ] } }, "type": "object" } } } }, "422": { "description": "As on registration, including advance_invoice_credit_must_be_total, advance_invoice_not_pending, sales_credit_note_exceeds_opening_total with `available`, and the line_credit_cap_* codes of drifted approved credits, plus sales_credit_note_cannot_be_modified. A line above its cap answers the SalesCreditNoteLineCapExceeded body.", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string" }, "error_code": { "type": "string", "example": "sales_credit_note_cannot_be_modified", "nullable": true }, "errors": { "type": "object", "nullable": true }, "advance_invoice_id": { "description": "Only on advance_invoice_not_pending: the advance invoice the note credits.", "type": "string", "format": "uuid" }, "advance_invoice_status": { "description": "Only on advance_invoice_not_pending: what the advance invoice is now.", "type": "string", "enum": [ "applied", "credited", "cancelled" ] }, "available": { "description": "Only on sales_credit_note_exceeds_opening_total: the opening remainder still available in the document currency.", "type": "string", "example": "58.00" }, "error": { "description": "Only on a globally rendered refusal: line_credit_cap_exceeded or sales_invoice_total_exceeds_storage.", "type": "string" } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/credit-notes": { "post": { "tags": [ "Backoffice - Sales Credit Notes" ], "summary": "Register a sales credit note from its origin invoice", "description": "Registers a Sales Credit Note as a draft (status to_be_approved) against an approved regular sales invoice of this company, against an Opening Document via Opening Rebate lines (MER-4638), or against an advance invoice pending application (`advance_pending`, MER-4264). The note inherits the origin's customer, currency, rate snapshot, client fiscal identity, receivable account, accounting center, payment term and location, never its sales order or reference, and posts nothing until it is approved. Its code is NC, the two-digit year and its own five-digit correlative. Each line credits one origin line, at most once per note: a unit_return is valued at the line's net unit price, an amount_rebate states its amount, and both must stay within what the line still has after the origin's approved credit notes (422 line_credit_cap_exceeded with the units and amount still available). An Opening Document has no lines: each line is an opening_rebate that states its catalog item, tax, center, account and a positive base; the note's gross must fit the opening remainder (422 sales_credit_note_exceeds_opening_total with `available`). A unit_return whose units have no amount left to credit is refused (sales_credit_note_line_without_amount). A regular origin must exist and be approved; an Opening Document must not be cancelled; an advance-invoice origin must be pending application (see below). A missing origin, a draft, a cancelled invoice or a note is refused with 422 sales_credit_note_origin_not_found, sales_credit_note_origin_not_approved, sales_credit_note_origin_cancelled or sales_credit_note_origin_is_a_note; a date before the origin's is refused with sales_credit_note_emission_date_precedes_origin. An advance invoice whose service is not rendered is credited only in full: every one of its lines by a unit_return of all its available units, so a missing line, fewer units or an amount_rebate, even of the whole amount, answers 422 advance_invoice_credit_must_be_total; an advance invoice already applied by a balance invoice, credited by another note or cancelled answers 422 advance_invoice_not_pending with advance_invoice_id and advance_invoice_status, and a draft one sales_credit_note_origin_not_approved. A debit note never takes an advance invoice. The fiscal numbers are kept as printed like an invoice's (ADR 0380); the control number shares the company's series with every invoice and note, so one another non-cancelled document holds, compared without whitespace or case (º counts as O), answers 409 naming its code and kind. The client generates the UUID `id`: resending it with the same terms answers 200 with the same body; with other terms, or an id another document holds, 409 sales_credit_note_id_conflict. The client also generates each line `id`: one that a line of any other document already holds answers 409 sales_credit_note_line_id_conflict, which names only the id sent. Requires `backoffice.sales.credit-notes.create`.", "operationId": "registerSalesCreditNote", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "id", "origin_sales_invoice_id", "emission_date", "reason", "lines" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "0199a000-0000-7000-8000-0000000002a1" }, "origin_sales_invoice_id": { "description": "The approved regular sales invoice, or the advance invoice pending application, this note affects.", "type": "string", "format": "uuid", "example": "0199a000-0000-7000-8000-0000000000a1" }, "emission_date": { "description": "On or after the origin's emission date.", "type": "string", "format": "date", "example": "2026-09-29" }, "reason": { "type": "string", "example": "return", "enum": [ "return", "discount", "price_correction", "quantity_correction", "other" ] }, "observations": { "description": "A free explanation of the reason.", "type": "string", "nullable": true }, "invoice_number": { "description": "The note's own printed number, kept as printed (ADR 0380): trimmed, with case, inner spaces and leading zeros kept, 1 to 30 letters, digits, spaces, hyphens, ° or º. Blank means absent.", "type": "string", "example": "00-000045", "nullable": true, "maxLength": 60 }, "control_number": { "description": "The note's own fiscal control number, kept as printed like invoice_number; unique among the company's non-cancelled invoices and notes, compared without whitespace or case (º counts as O).", "type": "string", "example": "00-00012346", "nullable": true, "maxLength": 60 }, "lines": { "description": "Line ids and origin lines are each distinct.", "type": "array", "items": { "$ref": "#/components/schemas/SalesCreditNoteLineInput" }, "minItems": 1 } }, "type": "object" } } } }, "responses": { "201": { "description": "Credit note registered as a draft", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesCreditNoteRegistered" } } } }, "200": { "description": "The same id was already registered with the same terms; nothing was written", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesCreditNoteRegistered" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks backoffice.sales.credit-notes.create" }, "409": { "description": "sales_credit_note_id_conflict: the id is already used with other terms or by another document; sales_credit_note_line_id_conflict: a line id is already used by a line of another document; or sales_invoice_control_number_already_registered, which also carries existing_code and existing_kind (see SalesDocumentControlNumberConflict)", "content": { "application/json": { "schema": { "required": [ "title", "status", "detail", "error_code" ], "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "detail": { "type": "string" }, "error_code": { "type": "string", "enum": [ "sales_credit_note_id_conflict", "sales_credit_note_line_id_conflict", "sales_invoice_control_number_already_registered" ] }, "existing_code": { "description": "Only on sales_invoice_control_number_already_registered: the code of the invoice or note that holds the control number, or null when it cannot be named.", "type": "string", "example": "INV2600007", "nullable": true }, "existing_kind": { "description": "Only on sales_invoice_control_number_already_registered: the kind of that document, null exactly when existing_code is null.", "type": "string", "nullable": true, "enum": [ "regular", "opening", "credit_note", "debit_note", "advance" ] } }, "type": "object" } } } }, "422": { "description": "Validation error (`errors`); a refused origin or date (sales_credit_note_origin_not_found, sales_credit_note_origin_not_approved, sales_credit_note_origin_cancelled, sales_credit_note_origin_is_a_note, advance_invoice_not_pending with advance_invoice_id and advance_invoice_status, sales_credit_note_emission_date_precedes_origin); refused lines (advance_invoice_credit_must_be_total, sales_credit_note_without_lines, sales_credit_note_line_repeated, sales_credit_note_origin_line_repeated, sales_credit_note_origin_line_not_found, sales_credit_note_line_credit_not_positive, sales_credit_note_line_without_amount, sales_credit_note_line_needs_origin_line, sales_credit_note_opening_rebate_needs_opening_origin); sales_credit_note_exceeds_opening_total with `available` when an Opening Rebate's gross exceeds the opening remainder (MER-4638); invalid_sales_credit_note_reason; invalid_invoice_number or invalid_control_number; line_credit_cap_returned_units_exceed_creditable or line_credit_cap_credited_amount_exceeds_creditable when the origin line's approved credit notes already exceed what it invoiced (drifted data). A line above its cap answers the SalesCreditNoteLineCapExceeded body instead, and totals beyond storage `{error: sales_invoice_total_exceeds_storage, detail}`.", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string" }, "error_code": { "type": "string", "example": "sales_credit_note_origin_not_approved", "nullable": true }, "errors": { "description": "The offending request fields, each with its messages.", "type": "object", "nullable": true }, "advance_invoice_id": { "description": "Only on advance_invoice_not_pending: the advance invoice the note credits.", "type": "string", "format": "uuid" }, "advance_invoice_status": { "description": "Only on advance_invoice_not_pending: what the advance invoice is now.", "type": "string", "enum": [ "applied", "credited", "cancelled" ] }, "error": { "description": "Only on a globally rendered refusal: line_credit_cap_exceeded or sales_invoice_total_exceeds_storage.", "type": "string" }, "line_id": { "description": "Only on line_credit_cap_exceeded.", "type": "string", "format": "uuid" }, "available_units": { "description": "Only on line_credit_cap_exceeded.", "type": "string" }, "available_amount": { "description": "Only on line_credit_cap_exceeded.", "type": "string" }, "currency": { "description": "Only on line_credit_cap_exceeded.", "type": "string" }, "available": { "description": "Only on sales_credit_note_exceeds_opening_total: the opening remainder still available in the document currency.", "type": "string", "example": "58.00" } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/credit-notes/proposed-fiscal-numbers": { "get": { "tags": [ "Backoffice - Sales Credit Notes" ], "summary": "Propose the fiscal numbers of the next sales credit note", "description": "Suggests the control number and the document number of the next credit note from the company's Active Control Series: the control number continues the series every invoice and note shares, the document number continues the credit notes' own numbering. Computed on every read and never reserved. Without an active series every field is null. Requires `backoffice.sales.credit-notes.create`.", "operationId": "proposeSalesCreditNoteFiscalNumbers", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The proposal", "content": { "application/json": { "schema": { "required": [ "active_control_series", "last_control_number", "proposed_control_number", "last_invoice_number", "proposed_invoice_number" ], "properties": { "active_control_series": { "type": "string", "example": "00", "nullable": true }, "last_control_number": { "type": "string", "example": "00-00012350", "nullable": true }, "proposed_control_number": { "type": "string", "example": "00-00012351", "nullable": true }, "last_invoice_number": { "description": "The last document number of a credit note.", "type": "string", "example": "000007", "nullable": true }, "proposed_invoice_number": { "description": "The next credit note's document number.", "type": "string", "example": "000008", "nullable": true } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks backoffice.sales.credit-notes.create" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/credit-notes/{id}/refund-preview": { "get": { "tags": [ "Backoffice - Sales Credit Notes" ], "summary": "Preview refunding a credit note's Customer Credit in cash", "description": "What a credit balance refund («devolución de saldo a favor», MER-3280) of the note's Customer Credit through one payment instrument on the date would record, by the same eligibility, Rate Snapshot rule, settlement and accounting readiness as registering it (POST /sales/collections with kind refund), over the treasury position as it stands, with nothing locked, written or counted: it refuses exactly what registering would. Without source_units it proposes the note's whole Customer Credit. The instrument must be in the note's currency (pick one from GET /treasury/payment-instruments/lookup). source_relieved is what the note gives up at its Carrying Amount, official_value the official value of the units paid out, treasury.posted the cash leg at its Carrying Amount (ADR 0197), and differences the note leg's debt_currency (leg source) and the cash leg's treasury_currency (leg treasury), signed from the company's side. Requires backoffice.sales.collections.refund.", "operationId": "previewSalesCreditNoteRefund", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "The credit note.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "instrument_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "date", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "source_units", "in": "query", "description": "Greater than zero, at most two decimals, in the note's currency; omitted, the note's whole Customer Credit. Through an instrument in another currency these are the units asked for: the response's source_units are what its money derives, or the whole Customer Credit when it derives that within the tolerance.", "required": false, "schema": { "type": "string", "pattern": "^(?!0+(?:\\.0{1,2})?$)\\d{1,13}(?:\\.\\d{1,2})?$" } } ], "responses": { "200": { "description": "What refunding would record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerCreditRefundPreview" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks backoffice.sales.collections.refund" }, "404": { "description": "sales_credit_note_not_found: the note does not exist or belongs to another company; or collection_instrument_not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesCreditApplicationProblem" } } } }, "409": { "description": "credit_balance_exceeded: the units exceed the note's Customer Credit, or the note already gave it all up; or cash_shift_not_open (with cash_register_id): the instrument's treasury account backs a Caja with no open Turno (MER-5688)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesCreditApplicationProblem" } } } }, "422": { "description": "The refusals of registering: validation (errors), refund_currency_mismatch, refund_amount_below_a_cent, application_source_not_open, application_date_precedes_credit_note, collection_instrument_inactive, collection_instrument_treasury_account_inactive, cash_event_date_in_the_future, unsupported_cash_event_currency, or the readiness envelope (OFFICIAL_RATE_STALE, OFFICIAL_RATE_NOT_AVAILABLE, CASH_BANK_ACCOUNT_*, RECEIVABLE_ACCOUNT_*, EXCHANGE_POSTING_ACCOUNT_MISSING, LEDGER_FLOW_NOT_PARALLEL_CURRENCY_READY, ACCOUNTING_PERIOD_CLOSED).", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/SalesCreditApplicationProblem" }, { "$ref": "#/components/schemas/SalesCreditApplicationAccountingConfigurationError" } ] } } } }, "500": { "description": "An integrity error, such as a note whose approval never posted its receivable" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/sales-invoices/{id}/creditable-lines": { "get": { "tags": [ "Backoffice - Sales Credit Notes" ], "summary": "What each line of a sales invoice can still credit", "description": "For an approved regular invoice, or an advance invoice pending application (MER-4264), each line with what it invoiced (its units, and its amount net of the line discount), what the invoice's approved debit notes added to it through linked increases, what the invoice's approved credit notes already returned and credited, and what is still available: invoiced plus increased, less credited. Draft and cancelled notes do not count, so the availability is a preview that approval checks again. An invoice that cannot be credited answers the same 422 codes as registration. origin_kind tells an advance invoice apart; when credit_must_be_total is true the note must return every available unit of each line by a unit_return, and registration refuses anything less with advance_invoice_credit_must_be_total. Requires `backoffice.sales.credit-notes.create`.", "operationId": "listSalesInvoiceCreditableLines", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The creditable lines", "content": { "application/json": { "schema": { "required": [ "origin_sales_invoice_id", "origin_code", "currency", "origin_kind", "credit_must_be_total", "lines" ], "properties": { "origin_sales_invoice_id": { "type": "string", "format": "uuid" }, "origin_code": { "type": "string", "example": "INV2600007" }, "currency": { "type": "string", "example": "USD" }, "origin_kind": { "description": "The kind of the invoice the note would credit.", "type": "string", "example": "regular", "enum": [ "regular", "advance", "opening" ] }, "credit_must_be_total": { "description": "True for an advance invoice: the note credits every available unit of each line.", "type": "boolean", "example": false }, "opening": { "description": "True when the origin is an Opening Document (MER-4638): lines is empty and creditable_total is the opening remainder.", "type": "boolean", "example": true }, "creditable_total": { "description": "Only for an Opening Document: opening total less approved credit notes' totals.", "type": "string", "example": "58.00" }, "lines": { "type": "array", "items": { "required": [ "origin_sales_invoice_item_id", "item_id", "item_name", "item_inventoried", "tax_id", "tax_percentage", "invoiced_units", "invoiced_amount", "increased_units", "increased_amount", "credited_units", "credited_amount", "available_units", "available_amount" ], "properties": { "origin_sales_invoice_item_id": { "type": "string", "format": "uuid" }, "item_id": { "type": "string", "format": "uuid" }, "item_name": { "type": "string" }, "item_inventoried": { "description": "Whether the item keeps stock. Returning its units credits the amount; what shipped comes back to stock only when someone receives its Return Entry (MER-4675, MER-2942).", "type": "boolean" }, "tax_id": { "type": "string", "format": "uuid" }, "tax_percentage": { "type": "string", "example": "16.00" }, "invoiced_units": { "type": "string", "example": "10.0000" }, "invoiced_amount": { "type": "string", "example": "100.00" }, "increased_units": { "description": "Units the approved debit notes added to the line", "type": "string", "example": "2.0000" }, "increased_amount": { "description": "Amount the approved debit notes added to the line", "type": "string", "example": "20.00" }, "credited_units": { "type": "string", "example": "8.0000" }, "credited_amount": { "type": "string", "example": "80.00" }, "available_units": { "type": "string", "example": "4.0000" }, "available_amount": { "type": "string", "example": "40.00" } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks backoffice.sales.credit-notes.create" }, "404": { "description": "sales_invoice_not_found" }, "422": { "description": "sales_credit_note_origin_not_approved, sales_credit_note_origin_cancelled or advance_invoice_not_pending (with advance_invoice_id and advance_invoice_status); or line_credit_cap_returned_units_exceed_creditable / line_credit_cap_credited_amount_exceeds_creditable when the approved credit notes already exceed what a line invoiced plus its approved increases (drifted data)" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/debit-notes/{id}/accounting-readiness": { "get": { "tags": [ "Backoffice - Sales Debit Notes" ], "summary": "Get the accounting readiness of a sales debit note", "description": "Whether approving the note could post its sales_debit_note.approved entry now (MER-3336), in the shape of every readiness endpoint. A draft (to_be_approved) is checked by the approval's own readiness: the origin invoice's receivable account and center, each line's revenue account and center, each taxed group's account and center, for a note of new concepts the official rate of its emission day (OFFICIAL_RATE_NOT_AVAILABLE), the parallel-currency flow and, last, the closed period of the note's emission date. The check runs on a plain read of the origin that locks and writes nothing, so it is a snapshot: approval reads the origin again under its lock and stays the authority. A note past its draft (to_be_collected, partially_collected, fully_collected, cancelled) has nothing left to approve and reads ready with no gaps. warnings is always empty for notes. A draft whose origin can no longer be debited is refused with the 422 its approval would answer. Requires `backoffice.sales.debit-notes.view`.", "operationId": "showSalesDebitNoteAccountingReadiness", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Accounting readiness snapshot; ready is true exactly when missing is empty", "content": { "application/json": { "schema": { "required": [ "ready", "missing", "warnings" ], "properties": { "ready": { "type": "boolean" }, "missing": { "type": "array", "items": { "required": [ "reason_code", "subject_type", "subject_id", "human_message", "details" ], "properties": { "reason_code": { "type": "string", "example": "ITEM_REVENUE_ACCOUNT_MISSING" }, "subject_type": { "type": "string", "example": "invoice_item" }, "subject_id": { "type": "string" }, "human_message": { "type": "string" }, "details": { "type": "array", "items": { "type": "string" } } }, "type": "object" } }, "warnings": { "$ref": "#/components/schemas/AccountingReadinessWarnings" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks backoffice.sales.debit-notes.view, or is not a member of the tenant" }, "404": { "description": "sales_debit_note_not_found: the note does not exist or belongs to another company, also for an invoice or a credit note id. An id that is not a UUID is answered by the router before the controller with a `message` body.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/SalesCreditApplicationProblem" }, { "required": [ "message" ], "properties": { "message": { "type": "string" } }, "type": "object" } ] } } } }, "422": { "description": "The draft's origin can no longer be debited, so its approval would refuse it for a reason that is not a configuration gap: sales_debit_note_origin_not_found, _is_opening, _not_approved, _cancelled or _is_a_note. The same codes the approval answers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesCreditApplicationProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/debit-notes/{id}/approve": { "post": { "tags": [ "Backoffice - Sales Debit Notes" ], "summary": "Approve a sales debit note", "description": "Approves a draft Sales Debit Note at the rate of its cause (ADR 0371). A note of linked increases keeps its origin's frozen rate snapshot and bolívar leg and reads no rate. A note of new concepts takes the rate snapshot and bolívar leg of its own emission day, selected as an invoice selects them, and a day with no rate refuses the approval with the gap OFFICIAL_RATE_NOT_AVAILABLE: the origin's rate is never the fallback. Each tax group's base is converted at that rate and its tax is a percentage of the functional base. The note becomes to_be_collected, owing its total in its three books, and posts `sales_debit_note.approved`: the receivable, debited on the center its origin's receivable settles on, against revenue per line on the line's account and center and output VAT per tax account and center. It posts no invoice entry, creates no inventory dispatch and leaves the sales order alone. The origin is re-read under its lock: one cancelled since registration answers 422 sales_debit_note_origin_cancelled. A note past its draft answers 422 sales_debit_note_cannot_be_modified, and a draft stored with lines of both types or a reason that contradicts them answers 422 sales_debit_note_mixed_causes or sales_debit_note_reason_disagrees_with_lines until it is revised. An entry that cannot post answers 422 `{error: accounting_configuration_incomplete, missing}` and writes nothing. Requires `backoffice.sales.debit-notes.approve`.", "operationId": "approveSalesDebitNote", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Approved", "content": { "application/json": { "schema": { "required": [ "sales_debit_note_id", "code", "status", "currency", "total", "functional_total", "reporting_total" ], "properties": { "sales_debit_note_id": { "type": "string", "format": "uuid" }, "code": { "type": "string", "example": "ND2600001" }, "status": { "type": "string", "enum": [ "to_be_collected" ] }, "currency": { "type": "string", "example": "USD" }, "total": { "type": "string", "example": "5.80" }, "functional_total": { "type": "string", "example": "638.00" }, "reporting_total": { "type": "string", "example": "5.80" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks backoffice.sales.debit-notes.approve" }, "404": { "description": "sales_debit_note_not_found" }, "422": { "description": "sales_debit_note_cannot_be_modified, a draft of more than one cause (sales_debit_note_mixed_causes, sales_debit_note_reason_disagrees_with_lines), a refused origin (sales_debit_note_origin_*), document_values_to_zero_in_both_books, or `{error: accounting_configuration_incomplete, missing}`" }, "500": { "description": "The entry could not read the note's origin, or could not persist" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/debit-notes/{id}/cancel": { "post": { "tags": [ "Backoffice - Sales Debit Notes" ], "summary": "Cancel a sales debit note", "description": "Cancels a Sales Debit Note in one transaction, locking its origin invoice, then the note. A draft is cancelled without an entry. An approved, uncollected note is cancelled and posts `sales_debit_note.cancelled`: the line-by-line inversion of its `sales_debit_note.approved` entry, dated the company's today and linked to the note; it keeps its balances as they stood. A partially or fully collected note answers 409 `sales_debit_note_has_collections`: cancel its collections first. A note a received VAT withholding relieved (`withheld_amount` above zero) answers 409 `sales_invoice_has_received_withholding`, checked after its collections: void the withholding first. A note whose linked increase an approved credit note of the origin credits answers 409 `sales_debit_note_increase_credited`, naming the affected origin lines and the origin's approved credit notes: cancel the credit note first. Cancelling again answers 200 and writes nothing. A note the current Declared Set of a Fiscal Period in review or closed holds answers 409 `document_in_frozen_fiscal_period` before anything is locked, naming the period in `fiscal_period` (MER-3837). Requires `backoffice.sales.debit-notes.cancel`.", "operationId": "cancelSalesDebitNote", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Debit note cancelled, or already cancelled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesDebitNoteCancelled" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks backoffice.sales.debit-notes.cancel" }, "404": { "description": "sales_debit_note_not_found, also for an invoice or a credit note id", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "detail": { "type": "string" }, "error_code": { "type": "string", "enum": [ "sales_debit_note_not_found" ] } }, "type": "object" } } } }, "409": { "description": "The note has collections (sales_debit_note_has_collections), a received withholding relieved it (sales_invoice_has_received_withholding), an approved credit note credits what it added (sales_debit_note_increase_credited, with `origin_sales_invoice_item_ids` and `credit_notes`), or a frozen fiscal period declared it (document_in_frozen_fiscal_period, with `fiscal_period`); nothing is written.", "content": { "application/json": { "schema": { "required": [ "title", "status", "detail", "error_code" ], "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "detail": { "type": "string" }, "error_code": { "type": "string", "enum": [ "sales_debit_note_has_collections", "sales_invoice_has_received_withholding", "sales_debit_note_increase_credited", "document_in_frozen_fiscal_period" ] }, "errors": { "type": "object", "nullable": true }, "origin_sales_invoice_item_ids": { "description": "Only for sales_debit_note_increase_credited: the origin lines credited beyond what they would keep.", "type": "array", "items": { "type": "string", "format": "uuid" } }, "credit_notes": { "description": "Only for sales_debit_note_increase_credited: the origin's approved credit notes, in id order.", "type": "array", "items": { "required": [ "id", "code", "kind", "status" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string", "example": "NC2600003" }, "kind": { "type": "string", "enum": [ "credit_note" ] }, "status": { "type": "string", "example": "with_customer_credit" } }, "type": "object" } }, "fiscal_period": { "description": "Only on document_in_frozen_fiscal_period: the period whose current Declared Set holds the document.", "allOf": [ { "$ref": "#/components/schemas/FrozenFiscalPeriod" } ] } }, "type": "object" } } } }, "500": { "description": "The approved entry is missing (sales_debit_note_posted_transaction_missing), the reversal could not be persisted, or a broken invariant" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/debit-notes/{id}/fiscal-identity": { "put": { "tags": [ "Backoffice - Sales Debit Notes" ], "summary": "Capture the fiscal numbers of a sales debit note", "description": "Records, or corrects, the fiscal numbers printed on the paper a Sales Debit Note represents, in any status but cancelled (ADR 0163). The numbers are kept as printed, like an invoice's (ADR 0380); the control number is unique among the company's non-cancelled invoices and notes, compared without whitespace or case (º counts as O). An unchanged capture writes nothing. A cancelled note answers 422 sales_debit_note_cannot_be_modified. A note the current Declared Set of a Fiscal Period in review or closed holds answers 409 document_in_frozen_fiscal_period first, naming the period in `fiscal_period` (MER-3837). Requires `backoffice.sales.debit-notes.approve`.", "operationId": "captureSalesDebitNoteFiscalIdentity", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "issued_in_contingency": { "description": "Mark the document as issued in contingency; omitted preserves the stored mark.", "type": "boolean" }, "contingency_reason": { "type": "string", "nullable": true, "enum": [ "power_failure", "internet_outage", "equipment_failure", "unplanned_maintenance", "fiscal_machine_unable", "third_party", "export", "multiple_copies", "other" ] }, "contingency_note": { "description": "Required for other cause.", "type": "string", "nullable": true, "maxLength": 500 }, "invoice_number": { "type": "string", "nullable": true, "maxLength": 60 }, "control_number": { "type": "string", "nullable": true, "maxLength": 60 }, "fiscal_machine_serial": { "description": "Serial printed by the fiscal machine; omitted keeps it, null or blank clears it.", "type": "string", "nullable": true, "maxLength": 60 } }, "type": "object" } } } }, "responses": { "200": { "description": "Captured" }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks backoffice.sales.debit-notes.approve" }, "404": { "description": "sales_debit_note_not_found" }, "409": { "description": "sales_invoice_control_number_already_registered, or document_in_frozen_fiscal_period when a frozen fiscal period declared the note", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/SalesDocumentControlNumberConflict" }, { "$ref": "#/components/schemas/DocumentInFrozenFiscalPeriodProblem" } ] } } } }, "422": { "description": "Validation error, invalid_invoice_number, invalid_control_number or invalid_fiscal_machine_serial, or sales_debit_note_cannot_be_modified for a cancelled note" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/debit-notes/{id}": { "get": { "tags": [ "Backoffice - Sales Debit Notes" ], "summary": "Show a sales debit note", "description": "The detail of a Sales Debit Note: the invoice detail's header, valuation and fiscal-identity keys, plus its origin, reason and lines. It uses the invoice statuses. While it awaits approval its totals are its lines' and its three open balances read 0.00; once approved it is valued at the rate of its cause, its origin's frozen rate for linked increases and its own day's for new concepts, and balance, functional_balance and reporting_balance are the debt it still holds open. The origin_* keys describe the invoice it affects (MER-3178). An invoice or credit-note id answers 404. Requires `backoffice.sales.debit-notes.view`.", "operationId": "showSalesDebitNote", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The debit note", "content": { "application/json": { "schema": { "required": [ "id", "code", "kind", "status", "origin_sales_invoice_id", "origin_code", "origin_invoice_number", "origin_control_number", "origin_emission_date", "origin_total", "origin_kind", "customer_id", "customer_name", "payment_term", "emission_date", "accounting_center_id", "accounting_account_receivable_id", "location_id", "reason", "reason_label", "observations", "subtotal", "discount", "taxes", "total", "balance", "withheld_amount", "currency", "invoice_number", "control_number", "issuance_channel", "fiscal_machine_serial", "client_fiscal_snapshot", "company_id", "lines", "tax_summaries" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string", "example": "ND2600001" }, "kind": { "type": "string", "enum": [ "debit_note" ] }, "status": { "type": "string", "example": "to_be_collected", "enum": [ "to_be_approved", "to_be_collected", "partially_collected", "fully_collected", "cancelled" ] }, "origin_sales_invoice_id": { "type": "string", "format": "uuid" }, "origin_code": { "type": "string", "example": "INV2600012", "nullable": true }, "origin_invoice_number": { "description": "The affected document's invoice number (MER-3178); null when it was never captured or the origin cannot be read.", "type": "string", "example": "00000123", "nullable": true }, "origin_control_number": { "description": "The affected document's control number; null when it was never captured or the origin cannot be read.", "type": "string", "example": "00-000456", "nullable": true }, "origin_emission_date": { "description": "The affected document's emission date; null only when the origin cannot be read.", "type": "string", "format": "date", "example": "2026-09-01", "nullable": true }, "origin_total": { "description": "Total of the affected invoice in its document currency; null if unreadable.", "type": "string", "example": "116.00", "nullable": true }, "origin_kind": { "description": "The affected document's kind (MER-4264); a debit note only ever affects a regular invoice; null only when the origin cannot be read.", "type": "string", "example": "regular", "nullable": true, "enum": [ "regular", null ] }, "customer_id": { "type": "string", "format": "uuid" }, "customer_name": { "type": "string", "nullable": true }, "payment_term": { "type": "string", "example": "cash", "enum": [ "cash", "five_days", "seven_days", "fifteen_days", "thirty_days" ] }, "emission_date": { "type": "string", "format": "date" }, "accounting_center_id": { "type": "string", "format": "uuid" }, "accounting_account_receivable_id": { "type": "string", "format": "uuid" }, "location_id": { "type": "string", "format": "uuid", "nullable": true }, "reason": { "type": "string", "enum": [ "interest", "freight", "price_correction", "quantity_correction", "other" ] }, "reason_label": { "type": "string", "example": "Intereses de mora" }, "observations": { "type": "string", "nullable": true }, "subtotal": { "type": "string", "example": "5.00" }, "discount": { "type": "string", "example": "0.00" }, "taxes": { "type": "string", "example": "0.80" }, "total": { "type": "string", "example": "5.80" }, "balance": { "description": "The debt the approved note still holds open in its currency; 0.00 while it awaits approval.", "type": "string", "example": "5.80" }, "withheld_amount": { "description": "What received VAT withholdings still standing on the note relieved of it, in its currency; 0.00 when none did. The client owes the total less this amount.", "type": "string", "example": "1.20" }, "currency": { "type": "string", "example": "USD" }, "functional_rate": { "type": "string" }, "reporting_rate": { "type": "string" }, "rate_rule": { "type": "string" }, "rate_value_date": { "type": "string", "format": "date" }, "functional_total": { "type": "string" }, "reporting_total": { "type": "string" }, "functional_balance": { "type": "string" }, "reporting_balance": { "type": "string" }, "invoice_number": { "type": "string", "nullable": true }, "control_number": { "type": "string", "nullable": true }, "issuance_channel": { "type": "string", "nullable": true }, "issuance_channel_mismatch": { "description": "Nonblocking warning: recorded note/origin channels differ, except a fiscal_machine_unable contingency, or a free_form origin when the note is dated from the PA SNAT/2026/00093 effective date (2027-04-19). False when either channel is unknown.", "type": "boolean" }, "issued_in_contingency": { "type": "boolean" }, "contingency_reason": { "type": "string", "nullable": true }, "contingency_note": { "type": "string", "nullable": true }, "contingency_reported_on": { "type": "string", "format": "date", "nullable": true }, "fiscal_machine_serial": { "description": "Always null: notes capture no fiscal machine serial yet (MER-4972).", "type": "string", "nullable": true }, "client_fiscal_snapshot": { "type": "object", "nullable": true }, "company_id": { "type": "string", "format": "uuid" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/SalesDebitNoteLine" } }, "tax_summaries": { "description": "Empty until the note is approved; then one per tax group, valued at the rate of its cause.", "type": "array", "items": { "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks backoffice.sales.debit-notes.view" }, "404": { "description": "sales_debit_note_not_found, also for an invoice or a credit note id" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Backoffice - Sales Debit Notes" ], "summary": "Revise a draft sales debit note", "description": "Replaces a draft Sales Debit Note's date, reason, observations, lines and, when sent, fiscal numbers. The note keeps its origin, whose header it inherits again; an origin cancelled since registration answers 422 sales_debit_note_origin_cancelled. Omitting both fiscal numbers keeps the stored pair; an explicit null clears them. A note past its draft answers 422 sales_debit_note_cannot_be_modified. The lines follow the registration's rules, one cause per note included: 422 sales_debit_note_mixed_causes or sales_debit_note_reason_disagrees_with_lines. Requires `backoffice.sales.debit-notes.create`.", "operationId": "updateSalesDebitNote", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "emission_date", "reason", "lines" ], "properties": { "emission_date": { "type": "string", "format": "date" }, "reason": { "type": "string", "enum": [ "interest", "freight", "price_correction", "quantity_correction", "other" ] }, "observations": { "type": "string", "nullable": true }, "invoice_number": { "type": "string", "nullable": true, "maxLength": 60 }, "control_number": { "type": "string", "nullable": true, "maxLength": 60 }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/SalesDebitNoteLineInput" }, "minItems": 1 } }, "type": "object" } } } }, "responses": { "200": { "description": "Revised" }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks backoffice.sales.debit-notes.create" }, "404": { "description": "sales_debit_note_not_found" }, "409": { "description": "sales_debit_note_line_id_conflict, or sales_invoice_control_number_already_registered, which also carries existing_code and existing_kind (see SalesDocumentControlNumberConflict)", "content": { "application/json": { "schema": { "required": [ "title", "status", "detail", "error_code" ], "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "detail": { "type": "string" }, "error_code": { "type": "string", "enum": [ "sales_debit_note_line_id_conflict", "sales_invoice_control_number_already_registered" ] }, "existing_code": { "description": "Only on sales_invoice_control_number_already_registered: the code of the document that holds the control number, or null when it cannot be named.", "type": "string", "nullable": true }, "existing_kind": { "description": "Only on sales_invoice_control_number_already_registered: the kind of that document, null exactly when existing_code is null.", "type": "string", "nullable": true, "enum": [ "regular", "opening", "credit_note", "debit_note", "advance" ] }, "errors": { "type": "object", "nullable": true } }, "type": "object" } } } }, "422": { "description": "Validation error (`errors`), sales_debit_note_cannot_be_modified, a refused origin or date, refused lines (sales_debit_note_mixed_causes and sales_debit_note_reason_disagrees_with_lines among them), invalid_sales_debit_note_reason, invalid fiscal numbers, invalid_money; a new concept's invalid tax answers `{error: sales_invoice_tax_selection_invalid, detail, tax_ids}`." }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/debit-notes": { "post": { "tags": [ "Backoffice - Sales Debit Notes" ], "summary": "Register a sales debit note from its origin invoice", "description": "Registers a Sales Debit Note as a draft (status to_be_approved) that raises what the customer owes on an approved regular sales invoice of this company. The note inherits the origin's customer, currency, client fiscal identity, receivable account, accounting center, payment term and location, never its sales order or reference, and posts nothing until it is approved. While it is a draft it reads its origin's rate snapshot; approval sets the one of its cause. Its code is ND, the two-digit year and its own five-digit correlative. Its reason is mandatory (Debit Note Reason). Lines are linked increases, which inherit their origin line, or new concepts, which bring their own item, tax and revenue account (see SalesDebitNoteLineInput); a debit note has no cap. A note has one cause, because its rate follows it: lines of both types answer 422 sales_debit_note_mixed_causes, and a reason that contradicts them 422 sales_debit_note_reason_disagrees_with_lines (a price or quantity correction takes linked increases, interest and freight new concepts, other either). The origin must exist and be an approved regular invoice: a missing one, an opening document, a draft, a cancelled invoice or a note is refused with 422 sales_debit_note_origin_not_found, sales_debit_note_origin_is_opening, sales_debit_note_origin_not_approved, sales_debit_note_origin_cancelled or sales_debit_note_origin_is_a_note; a date before the origin's is refused with sales_debit_note_emission_date_precedes_origin. The control number shares the company's series with every invoice and note, so one another non-cancelled document holds answers 409 naming its code and kind. The client generates the UUID `id`: resending it with the same terms answers 200 with the same body; with other terms, or an id another document holds, 409 sales_debit_note_id_conflict. A line id another document's line holds answers 409 sales_debit_note_line_id_conflict. Requires `backoffice.sales.debit-notes.create`.", "operationId": "registerSalesDebitNote", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "id", "origin_sales_invoice_id", "emission_date", "reason", "lines" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "0199a000-0000-7000-8000-0000000003b1" }, "origin_sales_invoice_id": { "description": "The approved regular sales invoice this note raises.", "type": "string", "format": "uuid" }, "emission_date": { "description": "On or after the origin's emission date.", "type": "string", "format": "date", "example": "2026-09-16" }, "reason": { "type": "string", "example": "interest", "enum": [ "interest", "freight", "price_correction", "quantity_correction", "other" ] }, "observations": { "description": "A free explanation of the reason.", "type": "string", "nullable": true }, "invoice_number": { "description": "The note's own printed number, kept as printed like an invoice's.", "type": "string", "nullable": true, "maxLength": 60 }, "control_number": { "description": "The note's own fiscal control number; unique among the company's non-cancelled invoices and notes.", "type": "string", "nullable": true, "maxLength": 60 }, "lines": { "description": "Line ids are distinct, and so are the origin lines of the linked increases.", "type": "array", "items": { "$ref": "#/components/schemas/SalesDebitNoteLineInput" }, "minItems": 1 } }, "type": "object" } } } }, "responses": { "201": { "description": "Debit note registered as a draft", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesDebitNoteRegistered" } } } }, "200": { "description": "The same id was already registered with the same terms; nothing was written", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesDebitNoteRegistered" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks backoffice.sales.debit-notes.create" }, "409": { "description": "sales_debit_note_id_conflict, sales_debit_note_line_id_conflict, or sales_invoice_control_number_already_registered, which also carries existing_code and existing_kind (see SalesDocumentControlNumberConflict)", "content": { "application/json": { "schema": { "required": [ "title", "status", "detail", "error_code" ], "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "detail": { "type": "string" }, "error_code": { "type": "string", "enum": [ "sales_debit_note_id_conflict", "sales_debit_note_line_id_conflict", "sales_invoice_control_number_already_registered" ] }, "existing_code": { "description": "Only on sales_invoice_control_number_already_registered.", "type": "string", "nullable": true }, "existing_kind": { "description": "Only on sales_invoice_control_number_already_registered.", "type": "string", "nullable": true, "enum": [ "regular", "opening", "credit_note", "debit_note", "advance" ] } }, "type": "object" } } } }, "422": { "description": "Validation error (`errors`); a refused origin or date (sales_debit_note_origin_*, sales_debit_note_emission_date_precedes_origin); refused lines (sales_debit_note_without_lines, sales_debit_note_line_repeated, sales_debit_note_origin_line_repeated, sales_debit_note_origin_line_not_found, sales_debit_note_line_increase_not_positive, sales_debit_note_line_without_amount, sales_debit_note_linked_increase_without_increase, sales_debit_note_new_concept_without_item, sales_debit_note_new_concept_without_tax, sales_debit_note_line_type_unknown, sales_debit_note_mixed_causes, sales_debit_note_reason_disagrees_with_lines); invalid_sales_debit_note_reason; invalid_invoice_number or invalid_control_number; invalid_money. A new concept's tax that is inactive or not at its catalog rate answers `{error: sales_invoice_tax_selection_invalid, detail, tax_ids}`, and totals beyond storage `{error: sales_invoice_total_exceeds_storage, detail}`.", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string" }, "error_code": { "type": "string", "example": "sales_debit_note_origin_not_approved", "nullable": true }, "errors": { "description": "The offending request fields, each with its messages.", "type": "object", "nullable": true }, "error": { "description": "Only on a globally rendered refusal: sales_invoice_tax_selection_invalid or sales_invoice_total_exceeds_storage.", "type": "string" }, "tax_ids": { "description": "Only on sales_invoice_tax_selection_invalid.", "type": "array", "items": { "type": "string", "format": "uuid" } } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/debit-notes/proposed-fiscal-numbers": { "get": { "tags": [ "Backoffice - Sales Debit Notes" ], "summary": "Propose the fiscal numbers of the next sales debit note", "description": "Suggests the control number and the document number of the next debit note from the company's Active Control Series: the control number continues the series every invoice and note shares, the document number continues the debit notes' own numbering. Computed on every read and never reserved. Without an active series every field is null. Requires `backoffice.sales.debit-notes.create`.", "operationId": "proposeSalesDebitNoteFiscalNumbers", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The proposal", "content": { "application/json": { "schema": { "required": [ "active_control_series", "last_control_number", "proposed_control_number", "last_invoice_number", "proposed_invoice_number" ], "properties": { "active_control_series": { "type": "string", "example": "00", "nullable": true }, "last_control_number": { "type": "string", "example": "00-00012350", "nullable": true }, "proposed_control_number": { "type": "string", "example": "00-00012351", "nullable": true }, "last_invoice_number": { "description": "The last document number of a debit note.", "type": "string", "example": "000003", "nullable": true }, "proposed_invoice_number": { "description": "The next debit note's document number.", "type": "string", "example": "000004", "nullable": true } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks backoffice.sales.debit-notes.create" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/item-availability/{id}": { "get": { "tags": [ "Backoffice - Sales - SalesOrders" ], "summary": "Read advisory sellable stock for a sales line", "operationId": "getSalesItemAvailability", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "location_id", "in": "query", "description": "Omit for the item total across company locations", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Base-unit sellable quantity (on hand minus reserved), null for a non-stock item", "content": { "application/json": { "schema": { "required": [ "sellable_quantity", "location_name" ], "properties": { "sellable_quantity": { "type": "string", "nullable": true }, "location_name": { "type": "string", "nullable": true } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Requires company membership and sales order, quote or invoice create/update permission" }, "404": { "description": "Item or location not found in this company" }, "422": { "description": "Invalid location id" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/contacts/{id}/opportunities": { "get": { "tags": [ "Backoffice - Sales - Opportunities" ], "summary": "List open opportunities for an authorized contact", "operationId": "496dcf6d3490bc7997e9cf785bc941e5", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Contact-Subject", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^\\+[1-9][0-9]{7,14}$" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpportunityProblem" } } } }, "403": { "description": "Insufficient permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpportunityProblem" } } } }, "404": { "description": "Opaque reference or tenant mismatch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpportunityProblem" } } } }, "200": { "description": "Successful result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpportunityList" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/opportunities/{id}": { "get": { "tags": [ "Backoffice - Sales - Opportunities" ], "summary": "Read the current authorized opportunity", "operationId": "51d56ea1f95662ade2ffd827847c7f43", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Contact-Subject", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^\\+[1-9][0-9]{7,14}$" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpportunityProblem" } } } }, "403": { "description": "Insufficient permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpportunityProblem" } } } }, "404": { "description": "Opaque reference or tenant mismatch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpportunityProblem" } } } }, "422": { "description": "Invalid subject or reference", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpportunityProblem" } } } }, "200": { "description": "Successful result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpportunityView" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "patch": { "tags": [ "Backoffice - Sales - Opportunities" ], "summary": "Update an open opportunity with an immutable effect", "operationId": "ca08c1c4baaaebc88090467852de7d21", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Contact-Subject", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^\\+[1-9][0-9]{7,14}$" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpportunityUpdateRequest" } } } }, "responses": { "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpportunityProblem" } } } }, "403": { "description": "Insufficient permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpportunityProblem" } } } }, "404": { "description": "Opaque reference or tenant mismatch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpportunityProblem" } } } }, "409": { "description": "Changed effect, contention or version conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpportunityProblem" } } } }, "422": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpportunityProblem" } } } }, "200": { "description": "Successful result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpportunityEffect" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/opportunities": { "post": { "tags": [ "Backoffice - Sales - Opportunities" ], "summary": "Open an independent commercial opportunity with an immutable effect", "operationId": "28158f9c8e549df58e4176f870ae0d40", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Contact-Subject", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^\\+[1-9][0-9]{7,14}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpportunityOpenRequest" } } } }, "responses": { "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpportunityProblem" } } } }, "403": { "description": "Insufficient permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpportunityProblem" } } } }, "404": { "description": "Opaque reference or tenant mismatch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpportunityProblem" } } } }, "409": { "description": "Changed effect, contention or version conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpportunityProblem" } } } }, "422": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpportunityProblem" } } } }, "201": { "description": "Opportunity created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpportunityEffect" } } } }, "200": { "description": "Successful replay", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpportunityEffect" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/pos/exception-approvals": { "post": { "tags": [ "Backoffice - Sales - Owner Step-Up Authorizations" ], "summary": "Request owner exception approval", "description": "Issues a single-use, 5-minute owner step-up authorization for an exceptional POS action (e.g. void_counter_sale). Caller POS Sanctum token is unchanged. Only the sha256 digest of the secret is persisted.", "operationId": "5c4a6f02b54cf80d18200104b33338e5", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "email", "password", "action", "subject_id" ], "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string", "format": "password" }, "action": { "type": "string", "enum": [ "void_counter_sale" ] }, "subject_id": { "type": "string", "format": "uuid" } }, "type": "object" } } } }, "responses": { "201": { "description": "Owner step-up authorization granted", "content": { "application/json": { "schema": { "required": [ "id", "token", "action", "subject_id", "granted_by", "expires_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "token": { "type": "string" }, "action": { "type": "string", "enum": [ "void_counter_sale" ] }, "subject_id": { "type": "string", "format": "uuid" }, "granted_by": { "required": [ "id", "name" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "type": "object" }, "expires_at": { "type": "string", "format": "date-time" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Missing counter-sales.sell" }, "422": { "description": "Validation error or owner_authorization_refused" }, "429": { "description": "Too many attempts" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/pos/sessions/current": { "get": { "tags": [ "Backoffice - Sales - POS Sessions" ], "summary": "Current POS session", "description": "Returns the authenticated POS session (no token). Requires a Sanctum token that reaches pos.surface.", "operationId": "36d4f33158e2214b4e295e81bc880f3d", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Current POS session without token" }, "401": { "description": "Unauthenticated" }, "404": { "description": "Tenant mismatch" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Backoffice - Sales - POS Sessions" ], "summary": "Sign out of POS", "description": "Ends the current POS session by deleting only the caller personal access token.", "operationId": "d2ff06738534dd970b4791df15f20435", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "POS session ended" }, "401": { "description": "Unauthenticated" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/pos/sessions": { "post": { "tags": [ "Backoffice - Sales - POS Sessions" ], "summary": "Sign in to POS", "description": "Starts a POS session for a company member with `counter-sales.sell`. Returns a Sanctum token with audience=pos (12h, read+write) that reaches only pos.surface routes.", "operationId": "d15f5c00d5c4774dc1706872ee4837ce", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "email", "password" ], "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string", "format": "password" } }, "type": "object" } } } }, "responses": { "201": { "description": "POS session created", "content": { "application/json": { "schema": { "required": [ "token", "expires_at", "user", "company_id", "permissions" ], "properties": { "token": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" }, "user": { "required": [ "id", "name" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "type": "object" }, "company_id": { "type": "string", "format": "uuid" }, "permissions": { "type": "array", "items": { "type": "string" } } }, "type": "object" } } } }, "403": { "description": "email_not_verified (login-identical body)" }, "422": { "description": "Validation error or pos_sign_in_refused" }, "429": { "description": "Too many attempts" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } } } }, "/api/backoffice/{tenant}/pos/sessions/switch": { "post": { "tags": [ "Backoffice - Sales - POS Sessions" ], "summary": "Switch POS seller", "description": "Rotates the POS session to another seller. On success mints a new audience=pos token and deletes the caller token inside a DB transaction. On refuse the caller token is kept.", "operationId": "2d97f9dfa7349ea1e62e7ea9fe419879", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "email", "password" ], "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string", "format": "password" } }, "type": "object" } } } }, "responses": { "201": { "description": "New POS session created" }, "403": { "description": "email_not_verified (login-identical body)" }, "422": { "description": "Validation error or pos_sign_in_refused" }, "429": { "description": "Too many attempts" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/potential-customers/{id}/convert": { "post": { "tags": [ "Backoffice - Sales - Potential Customers" ], "summary": "Convert a potential customer to a client", "description": "Transitions a pre_qualified or qualified potential customer to converted, against a new or an existing client. Without a choice, a new client is created unless clients of the company share the lead's name (same text, case and accents aside), phone (same last ten digits, punctuation and prefix aside) or email (case aside): then nothing is written and 409 lists them, at most ten, best match first, the Consumidor final never among them. Resend with link_to_client_id to convert against one of them (nothing on that client changes; its Activity records the lead), or with create_new to create a new client anyway. An invalid status transition is refused first, whatever the choice.", "operationId": "48b20aa10cb25f28727a1d53a483c6cc", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "0190b7a0-1111-7222-8333-444455556666" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "link_to_client_id": { "description": "An existing client of the company to convert against instead of creating one. Prohibits create_new; null is the same as absent.", "type": "string", "format": "uuid", "example": "0190b7a0-2222-4333-8444-555566667777", "nullable": true }, "create_new": { "description": "True creates a new client even when clients match. Send a JSON boolean; 1 and 0, as numbers or strings, are read as true and false.", "type": "boolean", "example": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Potential customer converted. linked_existing_client says whether client_id is the existing client named in link_to_client_id or a client this conversion created. A lead stored before MER-5240 may hold a phone or email the Client rule refuses: a new client is created without that contact, and dropped_contact_fields names each one (the value is kept on the client's creation Activity entry, never in this response). A link copies no contact, so it drops none.", "content": { "application/json": { "schema": { "required": [ "client_id", "dropped_contact_fields", "linked_existing_client" ], "properties": { "client_id": { "type": "string", "format": "uuid", "example": "0190b7a0-2222-4333-8444-555566667777" }, "dropped_contact_fields": { "description": "Empty when every contact reached the Client, and always empty on a link; phone before email.", "type": "array", "items": { "required": [ "field", "error_code" ], "properties": { "field": { "type": "string", "enum": [ "phone", "email" ] }, "error_code": { "type": "string", "enum": [ "invalid_counterparty_phone", "invalid_counterparty_email" ] } }, "type": "object" } }, "linked_existing_client": { "type": "boolean", "example": false } }, "type": "object" } } } }, "409": { "description": "No choice was sent and clients of the company match the lead; nothing was written. Each offered client names the fields it matched on, never their values.", "content": { "application/json": { "schema": { "required": [ "title", "status", "detail", "error_code", "errors", "matching_clients", "has_more_matching_clients" ], "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "detail": { "type": "string", "example": "Ya hay clientes que coinciden con este cliente potencial por nombre, teléfono o correo. Vincúlalo a uno de ellos o crea un cliente nuevo." }, "error_code": { "type": "string", "example": "potential_customer_has_matching_clients", "enum": [ "potential_customer_has_matching_clients" ] }, "errors": { "type": "object", "example": null, "nullable": true }, "matching_clients": { "description": "At most ten: most matched fields first, then active before inactive, then by code.", "type": "array", "items": { "required": [ "client_id", "code", "name", "status", "matched_on" ], "properties": { "client_id": { "type": "string", "format": "uuid" }, "code": { "type": "string", "example": "CLI2600001" }, "name": { "type": "string", "example": "QA Cliente A - Contribuyente ordinario (PN)" }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "matched_on": { "description": "Name before phone before email.", "type": "array", "items": { "type": "string", "enum": [ "name", "phone", "email" ] } } }, "type": "object" } }, "has_more_matching_clients": { "description": "True when more than ten clients matched.", "type": "boolean", "example": false } }, "type": "object" } } } }, "422": { "description": "Invalid status transition (checked first); the client named in link_to_client_id does not exist in the company or is its Consumidor final; or request validation failed (error_code null).", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string", "example": "Transición de estado del cliente potencial no válida de converted a converted" }, "error_code": { "description": "Null for request-validation failures.", "type": "string", "example": "invalid_potential_customer_status_transition", "nullable": true, "enum": [ "invalid_potential_customer_status_transition", "potential_customer_linked_client_not_found", "potential_customer_cannot_link_final_consumer", null ] }, "errors": { "description": "Null for an invalid status transition; otherwise keyed by link_to_client_id or create_new.", "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" } } } }, "404": { "description": "Potential customer not found", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "detail": { "type": "string", "example": "El cliente potencial con ID 0190b7a0-1111-7222-8333-444455556666 no existe" }, "error_code": { "type": "string", "example": "potential_customer_not_found" } }, "type": "object" } } } }, "403": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/potential-customers/{id}": { "get": { "tags": [ "Backoffice - Sales - Potential Customers" ], "summary": "Get a potential customer by ID", "operationId": "08727e15cda419e5f78677e3612c8fe1", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "0190b7a0-1111-7222-8333-444455556666" } } ], "responses": { "200": { "description": "Potential customer found successfully", "content": { "application/json": { "schema": { "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "phone": { "type": "string" }, "phone_kind": { "type": "string" }, "email": { "type": "string" }, "email_kind": { "type": "string" }, "source": { "type": "string" }, "status": { "type": "string", "enum": [ "pre_qualified", "contacting", "discovery", "qualified", "proposal", "converted", "lost", "nurture" ] }, "status_changed_at": { "type": "string", "format": "date-time" }, "lost_reason": { "type": "string", "nullable": true, "maxLength": 255 }, "next_action_note": { "type": "string", "nullable": true, "maxLength": 400 }, "next_action_at": { "type": "string", "format": "date-time", "nullable": true }, "assigned_salesperson_name": { "type": "string", "nullable": true }, "labels": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "tone": { "type": "string" }, "archived": { "type": "boolean" } }, "type": "object" } }, "assigned_salesperson_id": { "type": "integer", "nullable": true }, "creator_id": { "type": "integer" }, "converted_client_id": { "type": "string", "format": "uuid", "nullable": true }, "notes": { "type": "string", "nullable": true }, "last_activity_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "company_id": { "type": "string" } }, "type": "object" } } } }, "404": { "description": "Potential customer not found", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "detail": { "type": "string", "example": "El cliente potencial con ID 0190b7a0-1111-7222-8333-444455556666 no existe" } }, "type": "object" } } } }, "403": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Backoffice - Sales - Potential Customers" ], "summary": "Update a potential customer's contact data", "description": "Edits contact fields, source, notes, and the assigned salesperson. Status is not part of the request body. Omitting assigned_salesperson_id or sending null clears the assignment (Sin asignar); sending an integer assigns that salesperson.", "operationId": "b181648a4cfb0757976664b347d9c4e8", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "0190b7a0-1111-7222-8333-444455556666" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "phone", "phone_kind", "email", "email_kind", "source" ], "properties": { "name": { "type": "string", "example": "Maria Lopez", "maxLength": 80 }, "phone": { "description": "At least 6 digits and at most 30 characters, then the Client phone rule (MER-5240): only digits, spaces and + ( ) . -, so an extension such as \"ext. 2\" is refused with error_code invalid_counterparty_phone; note it in notes instead. Stored trimmed. A value byte-identical to the stored phone is kept as stored, even one that predates the rule.", "type": "string", "pattern": "^(?:\\D*\\d){6,}\\D*$", "example": "+18095551234", "maxLength": 30 }, "phone_kind": { "type": "string", "enum": [ "work", "personal", "other" ] }, "email": { "description": "The Client email rule (MER-5240): after trimming and lower-casing, PHP FILTER_VALIDATE_EMAIL must accept it, which is narrower than RFC 5322 (maria@localhost is refused) with error_code invalid_counterparty_email. Stored lower-cased. A value byte-identical to the stored email is kept as stored, even one that predates the rule.", "type": "string", "format": "email", "example": "maria@example.com", "maxLength": 255 }, "email_kind": { "type": "string", "enum": [ "work", "personal", "other" ] }, "source": { "type": "string", "enum": [ "social_media", "manager", "secretary", "website", "referral", "inbound_call" ] }, "assigned_salesperson_id": { "type": "integer", "nullable": true, "minimum": 1 }, "notes": { "type": "string", "nullable": true, "maxLength": 400 } }, "type": "object" } } } }, "responses": { "200": { "description": "Potential customer updated successfully" }, "404": { "description": "Potential customer not found", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "detail": { "type": "string", "example": "El cliente potencial con ID 0190b7a0-1111-7222-8333-444455556666 no existe" }, "error_code": { "type": "string", "example": "potential_customer_not_found" } }, "type": "object" } } } }, "422": { "description": "Request validation failed, or the Client rule refused a changed phone or email; errors names the refused field.", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string", "example": "El correo electrónico no es válido" }, "error_code": { "description": "Null for request-validation failures.", "type": "string", "example": "invalid_counterparty_email", "nullable": true, "enum": [ "invalid_counterparty_phone", "invalid_counterparty_email", null ] }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" } } } }, "409": { "description": "Converted lead cannot be reassigned", "content": { "application/json": { "schema": { "properties": { "error_code": { "type": "string", "example": "potential_customer_responsible_cannot_be_reassigned" } }, "type": "object" } } } }, "403": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Backoffice - Sales - Potential Customers" ], "summary": "Delete a potential customer", "description": "Hard-deletes a potential customer in any status except converted. Converted potential customers are the provenance record of a real client and cannot be deleted.", "operationId": "b9a26a6606eed97f0239166b6be42d17", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "0190b7a0-1111-7222-8333-444455556666" } } ], "responses": { "204": { "description": "Potential customer deleted successfully" }, "400": { "description": "Potential customer cannot be deleted", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Bad Request" }, "status": { "type": "integer", "example": 400 }, "detail": { "type": "string", "example": "El cliente potencial con ID 0190b7a0-1111-7222-8333-444455556666 no se puede eliminar mientras esté en estado converted" }, "error_code": { "type": "string", "example": "potential_customer_cannot_be_deleted" } }, "type": "object" } } } }, "404": { "description": "Potential customer not found", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "detail": { "type": "string", "example": "El cliente potencial con ID 0190b7a0-1111-7222-8333-444455556666 no existe" }, "error_code": { "type": "string", "example": "potential_customer_not_found" } }, "type": "object" } } } }, "403": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/potential-customers/{potentialCustomerId}/interactions/{interactionId}": { "put": { "tags": [ "Backoffice - Sales - Potential Customer Interactions" ], "summary": "Edit a logged interaction", "description": "Corrects the channel, direction, timestamp, or content of a manual bitácora entry.", "operationId": "d21fd36c2ee22ab83105278bb8bfdf2c", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "potentialCustomerId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "interactionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "channel", "direction", "occurred_at", "content" ], "properties": { "channel": { "type": "string", "enum": [ "whatsapp", "email", "call", "meeting", "in_person", "instagram", "other" ] }, "direction": { "type": "string", "enum": [ "outbound", "inbound" ] }, "occurred_at": { "description": "ISO-8601 instant. The UTC offset is required, as `Z` or `±HH:MM`; an offset-less timestamp is rejected with 422.", "type": "string", "format": "date-time", "example": "2026-05-15T11:30:00+00:00" }, "content": { "type": "string", "maxLength": 2000 } }, "type": "object" } } } }, "responses": { "200": { "description": "Interaction updated successfully" }, "404": { "description": "Interaction not found for this lead and tenant", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "error_code": { "type": "string", "example": "potential_customer_interaction_not_found" } }, "type": "object" } } } }, "422": { "description": "Validation error, an occurred_at without a UTC offset, an occurred_at in the future, or an auto-generated entry", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "error_code": { "type": "string", "enum": [ "potential_customer_interaction_occurred_in_the_future", "potential_customer_interaction_is_not_manual" ] } }, "type": "object" } } } }, "403": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Backoffice - Sales - Potential Customer Interactions" ], "summary": "Remove a logged interaction", "description": "Hard-deletes a manual bitácora entry. Deleting the lead itself cascades to every interaction it owns.", "operationId": "8d60152305073c38430e0bb3cb591141", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "potentialCustomerId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "interactionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Interaction deleted successfully" }, "404": { "description": "Interaction not found for this lead and tenant", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "error_code": { "type": "string", "example": "potential_customer_interaction_not_found" } }, "type": "object" } } } }, "422": { "description": "The entry is auto-generated and cannot be removed", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "error_code": { "type": "string", "example": "potential_customer_interaction_is_not_manual" } }, "type": "object" } } } }, "403": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/potential-customers/{potentialCustomerId}/interactions": { "get": { "tags": [ "Backoffice - Sales - Potential Customer Interactions" ], "summary": "List a potential customer's interaction timeline", "description": "Returns the lead's bitácora ordered by occurred_at descending. Timestamps are ISO-8601.", "operationId": "8ea5e0469ce927096d41a24e6a7a3aee", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "potentialCustomerId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "Interaction timeline", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "potential_customer_id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "manual", "system" ] }, "channel": { "type": "string", "nullable": true }, "direction": { "type": "string", "nullable": true }, "occurred_at": { "type": "string", "format": "date-time" }, "content": { "type": "string" }, "creator_name": { "description": "Company-scoped manual author name; system entries always null.", "type": "string", "nullable": true }, "creator_id": { "description": "Null on `system` entries, which the pipeline writes automatically and no user authored.", "type": "integer", "nullable": true } }, "type": "object" } }, "meta": { "properties": { "total": { "type": "integer" }, "per_page": { "type": "integer" }, "current_page": { "type": "integer" } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Potential customer not found", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "error_code": { "type": "string", "example": "potential_customer_not_found" } }, "type": "object" } } } }, "403": { "description": "Unauthorized" }, "422": { "description": "Validation error" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Sales - Potential Customer Interactions" ], "summary": "Log an interaction on a potential customer's timeline", "description": "Appends a manual entry to the lead's bitácora. The interaction bumps the lead's last_activity_at. A lead in any status, converted included, accepts interactions.", "operationId": "c3629339eefceb23e052f82f6fa1e952", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "potentialCustomerId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "id", "channel", "direction", "occurred_at", "content" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "0190b7a0-1111-7222-8333-444455556666" }, "channel": { "type": "string", "enum": [ "whatsapp", "email", "call", "meeting", "in_person", "instagram", "other" ] }, "direction": { "type": "string", "enum": [ "outbound", "inbound" ] }, "occurred_at": { "description": "ISO-8601 instant. The UTC offset is required, as `Z` or `±HH:MM`; an offset-less timestamp is rejected with 422.", "type": "string", "format": "date-time", "example": "2026-05-15T11:30:00+00:00" }, "content": { "type": "string", "example": "Sent the quote over WhatsApp.", "maxLength": 2000 } }, "type": "object" } } } }, "responses": { "201": { "description": "Interaction logged successfully" }, "404": { "description": "Potential customer not found", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "error_code": { "type": "string", "example": "potential_customer_not_found" } }, "type": "object" } } } }, "409": { "description": "Duplicate interaction ID", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "error_code": { "type": "string", "example": "potential_customer_interaction_already_exists" } }, "type": "object" } } } }, "422": { "description": "Validation error, an occurred_at without a UTC offset, or an occurred_at in the future", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "error_code": { "type": "string", "example": "potential_customer_interaction_occurred_in_the_future" } }, "type": "object" } } } }, "403": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/potential-customers/{id}/lost": { "post": { "tags": [ "Backoffice - Sales - Potential Customers" ], "summary": "Mark a potential customer as lost", "description": "Transitions any active potential customer to lost. A reason is mandatory: ADR 0084 retired the archived status precisely because it let a lead leave the funnel without one.", "operationId": "5013ba10460d93b9df103b3691180d7d", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "0190b7a0-1111-7222-8333-444455556666" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "lost_reason" ], "properties": { "lost_reason": { "type": "string", "example": "Se fue con la competencia", "maxLength": 255 } }, "type": "object" } } } }, "responses": { "200": { "description": "Potential customer marked as lost" }, "404": { "description": "Potential customer not found", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "error_code": { "type": "string", "example": "potential_customer_not_found" } }, "type": "object" } } } }, "422": { "description": "Validation error, a missing or blank reason, or an invalid status transition", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "error_code": { "type": "string", "example": "potential_customer_lost_reason_is_required" } }, "type": "object" } } } }, "403": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/potential-customers/{id}/next-action": { "put": { "tags": [ "Backoffice - Sales - Potential Customers" ], "summary": "Set or clear a potential customer's next action", "description": "Replaces the whole Next Action sub-resource. Both keys are required; sending both as null clears the commitment. A past date is accepted — overdue is a first-class state of the work queue, unlike the nurture reactivation date, which must be in the future.", "operationId": "32d722b9bc2ee42124954164f635519a", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "0190b7a0-1111-7222-8333-444455556666" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "next_action_note", "next_action_at" ], "properties": { "next_action_note": { "description": "What is owed to this lead. Optional on its own, but only alongside a date.", "type": "string", "example": "Llamar para cerrar la propuesta", "nullable": true, "maxLength": 400 }, "next_action_at": { "description": "ISO-8601 instant, past or future. The UTC offset is required, as `Z` or `±HH:MM`; an offset-less timestamp is rejected with 422.", "type": "string", "format": "date-time", "example": "2027-03-01T09:00:00+00:00", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Next action set or cleared" }, "404": { "description": "Potential customer not found", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "error_code": { "type": "string", "example": "potential_customer_not_found" } }, "type": "object" } } } }, "422": { "description": "Validation error, a note without a date, a date without a UTC offset, or clearing the next action of a parked lead", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "error_code": { "type": "string", "enum": [ "potential_customer_next_action_date_is_required", "potential_customer_next_action_cannot_be_cleared_while_nurtured" ] } }, "type": "object" } } } }, "403": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/potential-customers": { "get": { "tags": [ "Backoffice - Sales - Potential Customers" ], "summary": "List potential customers with pagination, filters, and global per-status counts", "description": "The list is the sales team's work queue, so the default order is `next_action_at` ascending with nulls last: what is owed soonest leads, and the leads owing nothing sink to the bottom. Ties break by `created_at` descending — the previous default, so leads without a next action come back in the order this list has always shown — and then by `id` descending, which keeps offset pagination deterministic once a whole bucket ties.", "operationId": "d127c0525b711acadfce3ae94a0ba417", "parameters": [ { "name": "view", "in": "query", "required": false, "schema": { "type": "string", "default": "all", "enum": [ "active", "all" ] } }, { "name": "label_ids[]", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" } } }, { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1 } }, { "name": "status", "in": "query", "description": "One or more funnel statuses. Canonical form is comma-separated; bracket arrays are accepted for compatibility.", "required": false, "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "pre_qualified", "contacting", "discovery", "qualified", "proposal", "converted", "lost", "nurture" ] } } }, { "name": "source", "in": "query", "description": "One or more contact sources. Canonical form is comma-separated; bracket arrays are accepted for compatibility.", "required": false, "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "social_media", "manager", "secretary", "website", "referral", "inbound_call" ] } } }, { "name": "assigned_salesperson_id", "in": "query", "description": "One or more salesperson IDs belonging to the tenant.", "required": false, "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "integer", "minimum": 1 } } }, { "name": "urgency", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "overdue", "today", "upcoming", "without_next_action" ] } }, { "name": "created_from", "in": "query", "description": "Inclusive first Company-local creation day; may be supplied without created_to.", "required": false, "schema": { "type": "string", "format": "date", "example": "2026-08-08" } }, { "name": "created_to", "in": "query", "description": "Inclusive last Company-local creation day; may be supplied alone and cannot precede created_from.", "required": false, "schema": { "type": "string", "format": "date", "example": "2026-08-08" } }, { "name": "inactive_for_days", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 } }, { "name": "sort_by", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "next_action_at", "last_activity_at", "created_at" ] } }, { "name": "sort_order", "in": "query", "description": "Requires sort_by. Defaults to asc for next_action_at and desc otherwise.", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "search", "in": "query", "description": "Prefer POST /potential-customers/search for this filter: a query string carries the fragment into access logs, browser history, and Referer headers.", "required": false, "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "200": { "description": "Potential customers list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PotentialCustomersSearchResponse" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "404": { "description": "Company not found" }, "422": { "description": "Validation error" }, "500": { "description": "Potential customer search failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PotentialCustomersSearchFailureProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Sales - Potential Customers" ], "summary": "Capture a new potential customer", "description": "Creates a potential customer with contact data, source, and an initial status of pre_qualified or qualified.", "operationId": "90e6aca19f928c68779a39e3a892e285", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "id", "name", "phone", "phone_kind", "email", "email_kind", "source" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "0190b7a0-1111-7222-8333-444455556666" }, "name": { "type": "string", "example": "Maria Lopez", "maxLength": 80 }, "phone": { "description": "At least 6 digits and at most 30 characters, then the Client phone rule (MER-5240): only digits, spaces and + ( ) . -, so an extension such as \"ext. 2\" is refused with error_code invalid_counterparty_phone; note it in notes instead. Stored trimmed.", "type": "string", "pattern": "^(?:\\D*\\d){6,}\\D*$", "example": "+18095551234", "maxLength": 30 }, "phone_kind": { "type": "string", "enum": [ "work", "personal", "other" ] }, "email": { "description": "The Client email rule (MER-5240): after trimming and lower-casing, PHP FILTER_VALIDATE_EMAIL must accept it, which is narrower than RFC 5322 (maria@localhost is refused) with error_code invalid_counterparty_email. Stored lower-cased.", "type": "string", "format": "email", "example": "maria@example.com", "maxLength": 255 }, "email_kind": { "type": "string", "enum": [ "work", "personal", "other" ] }, "source": { "type": "string", "enum": [ "social_media", "manager", "secretary", "website", "referral", "inbound_call" ] }, "status": { "type": "string", "nullable": true, "enum": [ "pre_qualified", "qualified" ] }, "assigned_salesperson_id": { "type": "integer", "nullable": true, "minimum": 1 }, "notes": { "type": "string", "nullable": true, "maxLength": 400 } }, "type": "object" } } } }, "responses": { "201": { "description": "Potential customer created successfully" }, "409": { "description": "Duplicate potential customer ID", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "detail": { "type": "string", "example": "El cliente potencial con ID 0190b7a0-1111-7222-8333-444455556666 ya existe" }, "error_code": { "type": "string", "example": "potential_customer_already_exists" } }, "type": "object" } } } }, "422": { "description": "Request validation failed, or the Client rule refused the phone or the email; errors names the refused field.", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string", "example": "El teléfono debe tener entre 1 y 32 caracteres entre dígitos y signos de puntuación telefónica" }, "error_code": { "description": "Null for request-validation failures.", "type": "string", "example": "invalid_counterparty_phone", "nullable": true, "enum": [ "invalid_counterparty_phone", "invalid_counterparty_email", null ] }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unauthorized" }, "status": { "type": "integer", "example": 403 }, "detail": { "type": "string", "example": "You do not have permission to access this resource." } }, "type": "object" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Internal Server Error" }, "status": { "type": "integer", "example": 500 }, "detail": { "type": "string", "example": "An Unexpected Error Occurred" } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/potential-customers/{id}/qualify": { "post": { "tags": [ "Backoffice - Sales - Potential Customers" ], "summary": "Qualify a potential customer", "description": "Transitions a pre_qualified potential customer to qualified.", "operationId": "39972f9d45bc574847ddc522de4c76c1", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "0190b7a0-1111-7222-8333-444455556666" } } ], "responses": { "200": { "description": "Potential customer qualified successfully" }, "422": { "description": "Invalid status transition", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string", "example": "Transición de estado del cliente potencial no válida de qualified a qualified" }, "error_code": { "type": "string", "example": "invalid_potential_customer_status_transition" } }, "type": "object" } } } }, "404": { "description": "Potential customer not found", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "detail": { "type": "string", "example": "El cliente potencial con ID 0190b7a0-1111-7222-8333-444455556666 no existe" }, "error_code": { "type": "string", "example": "potential_customer_not_found" } }, "type": "object" } } } }, "403": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/potential-customers/{id}/reactivate": { "post": { "tags": [ "Backoffice - Sales - Potential Customers" ], "summary": "Reactivate a parked potential customer", "description": "Returns a nurture potential customer to contacting when its reactivation date arrives.", "operationId": "ad6e641e994f689ff1d8d92bd08508b3", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "0190b7a0-1111-7222-8333-444455556666" } } ], "responses": { "200": { "description": "Potential customer reactivated" }, "404": { "description": "Potential customer not found", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "detail": { "type": "string", "example": "El cliente potencial con ID 0190b7a0-1111-7222-8333-444455556666 no existe" }, "error_code": { "type": "string", "example": "potential_customer_not_found" } }, "type": "object" } } } }, "422": { "description": "Invalid status transition", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string", "example": "Transición de estado del cliente potencial no válida de lost a contacting" }, "error_code": { "type": "string", "example": "invalid_potential_customer_status_transition" } }, "type": "object" } } } }, "403": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/potential-customers/{id}/proposal": { "post": { "tags": [ "Backoffice - Sales - Potential Customers" ], "summary": "Record that a proposal was sent to a potential customer", "description": "Transitions a potential customer to proposal - a written proposal is in the hands of the buyer.", "operationId": "e895cbc5183cd403ca398cf9374958fc", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "0190b7a0-1111-7222-8333-444455556666" } } ], "responses": { "200": { "description": "Potential customer moved to proposal" }, "404": { "description": "Potential customer not found", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "detail": { "type": "string", "example": "El cliente potencial con ID 0190b7a0-1111-7222-8333-444455556666 no existe" }, "error_code": { "type": "string", "example": "potential_customer_not_found" } }, "type": "object" } } } }, "422": { "description": "Invalid status transition", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string", "example": "Transición de estado del cliente potencial no válida de converted a proposal" }, "error_code": { "type": "string", "example": "invalid_potential_customer_status_transition" } }, "type": "object" } } } }, "403": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/potential-customers/{id}/reopen": { "post": { "tags": [ "Backoffice - Sales - Potential Customers" ], "summary": "Reopen a lost potential customer", "description": "Explicitly returns a lost potential customer to contacting.", "operationId": "e58e4fb4c9ee3e7dc58a9f565ecfb5f8", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "0190b7a0-1111-7222-8333-444455556666" } } ], "responses": { "200": { "description": "Potential customer reopened" }, "404": { "description": "Potential customer not found", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "detail": { "type": "string", "example": "El cliente potencial con ID 0190b7a0-1111-7222-8333-444455556666 no existe" }, "error_code": { "type": "string", "example": "potential_customer_not_found" } }, "type": "object" } } } }, "422": { "description": "Invalid status transition", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string", "example": "Transición de estado del cliente potencial no válida de nurture a contacting" }, "error_code": { "type": "string", "example": "invalid_potential_customer_status_transition" } }, "type": "object" } } } }, "403": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/potential-customers/{id}/responsible": { "put": { "tags": [ "Backoffice - Sales - Potential Customers" ], "summary": "Reassign the responsible salesperson", "operationId": "360f71ea4c0b0692a1e4ead510c97f14", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "assigned_salesperson_id" ], "properties": { "assigned_salesperson_id": { "type": "integer", "nullable": true, "minimum": 1 } }, "type": "object" } } } }, "responses": { "200": { "description": "Assigned, cleared, or unchanged" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" } }, "type": "object" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" } }, "type": "object" } } } }, "404": { "description": "Missing or foreign lead", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "error_code": { "type": "string", "example": "potential_customer_not_found" } }, "type": "object" } } } }, "409": { "description": "Converted lead cannot be reassigned", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "error_code": { "type": "string", "example": "potential_customer_responsible_cannot_be_reassigned" } }, "type": "object" } } } }, "422": { "description": "Invalid or foreign responsible", "content": { "application/json": { "schema": { "oneOf": [ { "properties": { "message": { "type": "string" }, "errors": { "type": "object" } }, "type": "object" }, { "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "errors": { "type": "object" } }, "type": "object" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/potential-customers/{id}/nurture": { "post": { "tags": [ "Backoffice - Sales - Potential Customers" ], "summary": "Park a potential customer until a reactivation date", "description": "Transitions any active potential customer to nurture. The reactivation date is mandatory and must be in the future: no parked lead without a return date (ADR 0084).", "operationId": "aab0641e5ad8ed7bea03172a0f034470", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "0190b7a0-1111-7222-8333-444455556666" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "next_action_at" ], "properties": { "next_action_at": { "description": "ISO-8601 instant in the future. The UTC offset is required, as `Z` or `±HH:MM`; an offset-less timestamp is rejected with 422.", "type": "string", "format": "date-time", "example": "2027-03-01T09:00:00+00:00" }, "next_action_note": { "description": "What is owed to this lead when it comes back. Optional; blank or whitespace-only is stored as null. Persisted by this same request — no follow-up call to PUT …/next-action.", "type": "string", "example": "Retomar contacto para cerrar la propuesta", "nullable": true, "maxLength": 400 } }, "type": "object" } } } }, "responses": { "200": { "description": "Potential customer parked until its reactivation date" }, "404": { "description": "Potential customer not found", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "error_code": { "type": "string", "example": "potential_customer_not_found" } }, "type": "object" } } } }, "422": { "description": "Validation error, a next_action_at without a UTC offset or not in the future, a next_action_note longer than 400 characters, or an invalid status transition", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "error_code": { "type": "string", "example": "potential_customer_nurture_date_must_be_in_the_future" } }, "type": "object" } } } }, "403": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/potential-customers/{id}/contacting": { "post": { "tags": [ "Backoffice - Sales - Potential Customers" ], "summary": "Start contacting a potential customer", "description": "Transitions a potential customer to contacting - outreach has begun.", "operationId": "bb93990871e0b8e8311fe993a6df9c3d", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "0190b7a0-1111-7222-8333-444455556666" } } ], "responses": { "200": { "description": "Potential customer moved to contacting" }, "404": { "description": "Potential customer not found", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "detail": { "type": "string", "example": "El cliente potencial con ID 0190b7a0-1111-7222-8333-444455556666 no existe" }, "error_code": { "type": "string", "example": "potential_customer_not_found" } }, "type": "object" } } } }, "422": { "description": "Invalid status transition", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string", "example": "Transición de estado del cliente potencial no válida de converted a contacting" }, "error_code": { "type": "string", "example": "invalid_potential_customer_status_transition" } }, "type": "object" } } } }, "403": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/potential-customers/{id}/discovery": { "post": { "tags": [ "Backoffice - Sales - Potential Customers" ], "summary": "Start discovery on a potential customer", "description": "Transitions a potential customer to discovery - a meeting with an agreed purpose and date exists.", "operationId": "f34f7d6122418946963407a061d78e06", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "0190b7a0-1111-7222-8333-444455556666" } } ], "responses": { "200": { "description": "Potential customer moved to discovery" }, "404": { "description": "Potential customer not found", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "detail": { "type": "string", "example": "El cliente potencial con ID 0190b7a0-1111-7222-8333-444455556666 no existe" }, "error_code": { "type": "string", "example": "potential_customer_not_found" } }, "type": "object" } } } }, "422": { "description": "Invalid status transition", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string", "example": "Transición de estado del cliente potencial no válida de proposal a discovery" }, "error_code": { "type": "string", "example": "invalid_potential_customer_status_transition" } }, "type": "object" } } } }, "403": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/potential-customers/search": { "post": { "tags": [ "Backoffice - Sales - Potential Customers" ], "summary": "Search potential customers by name, phone, or email without placing them in the URL", "description": "Same work queue, ordering, pagination, and global counts as the GET list, but every filter travels in the JSON body so a lead's name, phone number, or e-mail address never reaches a URL, an access log, a browser history entry, a Referer header, or an observability payload. The operation only reads: it accepts no query parameters and answers 200, not 201.", "operationId": "8201079984d7bb1702153a5cfdb952d3", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PotentialCustomersSearchRequest" } } } }, "responses": { "200": { "description": "Potential customers list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PotentialCustomersSearchResponse" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "404": { "description": "Company not found" }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PotentialCustomersSearchValidationProblem" } } } }, "500": { "description": "Potential customer search failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PotentialCustomersSearchFailureProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/price-lists/lookup": { "get": { "tags": [ "Backoffice - Sales - Price List Lookups" ], "summary": "Lookup price lists for tenant forms (active, or one by id)", "description": "Tenant membership is enough; no module permission is required (MER-3894). Lists only the company's active price lists, ordered by name then code, optionally in one currency, for the sales quote form. With id (MER-5239) it answers that one list of the company whatever its status or currency, so a form names a stored list that is inactive; another company's or an unknown id answers an empty page, and a blank id is absent. Every item carries its status. It exposes no price: a line's price comes from POST sales/prices/resolve.", "operationId": "784abeeb8072b023a74ff7005dbd98d9", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "query", "description": "One stored list of the company, whatever its status or currency; currency is then ignored.", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "currency", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "USD", "VES" ] } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 200, "minimum": 1 } } ], "responses": { "200": { "description": "Minimal price list projection: the active lists, or the one asked by id", "content": { "application/json": { "schema": { "required": [ "items", "total", "per_page", "current_page" ], "properties": { "items": { "type": "array", "items": { "required": [ "id", "code", "name", "currency", "status" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string", "example": "MAYOR" }, "name": { "type": "string", "example": "Precios al mayor" }, "currency": { "type": "string", "enum": [ "USD", "VES" ] }, "status": { "type": "string", "enum": [ "active", "inactive" ] } }, "type": "object" } }, "total": { "type": "integer" }, "per_page": { "type": "integer" }, "current_page": { "type": "integer" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Not a member of this tenant" }, "404": { "description": "Tenant not found" }, "422": { "description": "Invalid id, currency or pagination" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/price-lists/{priceListId}/activation": { "put": { "tags": [ "Backoffice - Sales - Price Lists" ], "summary": "Activate a price list", "description": "Activates an inactive list, so it prices sales again. Only an inactive list is activated; an active one answers 409 price_list_status_transition_not_allowed with price_list_status.", "operationId": "b8d499bc85b9a2e9fb8e97c95dcacd61", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "priceListId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Price list status changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceListWriteResponse" } } } }, "401": { "description": "Unauthenticated: the auth middleware answers before the controller", "content": { "application/json": { "schema": { "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "403": { "description": "Missing backoffice.sales.price-lists.manage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceListProblem" } } } }, "404": { "description": "price_list_not_found from the controller, or the middleware's message for an unknown company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceListNotFound404" } } } }, "409": { "description": "price_list_status_transition_not_allowed (with price_list_status)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceListProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/price-lists/{priceListId}/deactivation": { "put": { "tags": [ "Backoffice - Sales - Price Lists" ], "summary": "Deactivate a price list", "description": "Deactivates an active list: it is kept, and its prices stay editable, but it prices no sale. Only an active list is deactivated; an inactive one answers 409 price_list_status_transition_not_allowed with price_list_status. A list a sales channel of the company names as its default, of any kind or status, is not deactivated (MER-5239): it answers 409 price_list_in_use_by_sales_channels with sales_channels (at most 10, by code) and sales_channels_total, and nothing changes.", "operationId": "ec2c26ff527db6b33b66fea78396e179", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "priceListId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Price list status changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceListWriteResponse" } } } }, "401": { "description": "Unauthenticated: the auth middleware answers before the controller", "content": { "application/json": { "schema": { "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "403": { "description": "Missing backoffice.sales.price-lists.manage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceListProblem" } } } }, "404": { "description": "price_list_not_found from the controller, or the middleware's message for an unknown company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceListNotFound404" } } } }, "409": { "description": "price_list_status_transition_not_allowed (with price_list_status), or price_list_in_use_by_sales_channels (with sales_channels and sales_channels_total)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceListProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/price-lists/{priceListId}/entries": { "get": { "tags": [ "Backoffice - Sales - Price Lists" ], "summary": "List the prices of a price list", "description": "A page of the list's prices, each with its item's code, name, barcode, SKU and status, ordered by item name then minimum quantity. A list without prices answers an empty page.", "operationId": "d2961a7e505e4e58ed3bc3e620adb6c4", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "priceListId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "search", "in": "query", "description": "Matches part of the item's code, name, barcode or SKU.", "required": false, "schema": { "type": "string", "maxLength": 100 } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 25, "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "Prices found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceListEntryList" } } } }, "401": { "description": "Unauthenticated: the auth middleware answers before the controller", "content": { "application/json": { "schema": { "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "403": { "description": "Missing backoffice.sales.price-lists.view", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceListProblem" } } } }, "404": { "description": "price_list_not_found from the controller, or the middleware's message for an unknown company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceListNotFound404" } } } }, "422": { "description": "Request validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceListProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Sales - Price Lists" ], "summary": "Price an item under a price list", "description": "Prices an active item of the company's catalog from a minimum quantity, in the list's currency. A list prices an item once per minimum quantity. An inactive list still takes prices.", "operationId": "38e9cf21863d9ffbb9bb9784019be90e", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "priceListId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceListEntryCreateRequest" } } } }, "responses": { "201": { "description": "Price added", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceListEntryWriteResponse" } } } }, "401": { "description": "Unauthenticated: the auth middleware answers before the controller", "content": { "application/json": { "schema": { "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "403": { "description": "Missing backoffice.sales.price-lists.manage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceListProblem" } } } }, "404": { "description": "price_list_not_found from the controller, or the middleware's message for an unknown company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceListNotFound404" } } } }, "409": { "description": "price_list_entry_id_already_taken, or price_list_entry_already_exists with field_errors.min_quantity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceListProblem" } } } }, "422": { "description": "Request validation failed, or price_list_entry_item_not_found, price_list_entry_item_inactive, price_list_entry_min_quantity_invalid, price_list_entry_unit_price_invalid or price_list_entry_currency_mismatch (with price_list_currency) with field_errors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceListRefusal422" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/price-lists/{priceListId}/entries/{entryId}": { "put": { "tags": [ "Backoffice - Sales - Price Lists" ], "summary": "Change a price of a price list", "description": "Rewrites the minimum quantity and the amount; the price keeps its item and its currency, and stays editable after its item is inactivated. A change that changes nothing still answers 200 and records nothing. A price of another list is not found.", "operationId": "48ef83c27364a2df7b1224dc2e3bf4b6", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "priceListId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "entryId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceListEntryUpdateRequest" } } } }, "responses": { "200": { "description": "Price changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceListEntryWriteResponse" } } } }, "401": { "description": "Unauthenticated: the auth middleware answers before the controller", "content": { "application/json": { "schema": { "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "403": { "description": "Missing backoffice.sales.price-lists.manage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceListProblem" } } } }, "404": { "description": "price_list_entry_not_found from the controller, or the middleware's message for an unknown company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceListNotFound404" } } } }, "409": { "description": "price_list_entry_already_exists with field_errors.min_quantity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceListProblem" } } } }, "422": { "description": "Request validation failed, or price_list_entry_min_quantity_invalid, price_list_entry_unit_price_invalid or price_list_entry_currency_mismatch (with price_list_currency) with field_errors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceListRefusal422" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Backoffice - Sales - Price Lists" ], "summary": "Remove a price from a price list", "description": "Removes the price; the list's history keeps what it was. A price of another list is not found.", "operationId": "82f0decac6a0fdaec11092ff6690ea67", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "priceListId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "entryId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Price removed" }, "401": { "description": "Unauthenticated: the auth middleware answers before the controller", "content": { "application/json": { "schema": { "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "403": { "description": "Missing backoffice.sales.price-lists.manage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceListProblem" } } } }, "404": { "description": "price_list_entry_not_found from the controller, or the middleware's message for an unknown company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceListNotFound404" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/price-lists/{priceListId}": { "get": { "tags": [ "Backoffice - Sales - Price Lists" ], "summary": "Show a price list", "description": "The list with its timestamps. Another company's list is not found.", "operationId": "1b0b59f6a94d7af0f03e410ef4b499f4", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "priceListId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Price list found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceList" } } } }, "401": { "description": "Unauthenticated: the auth middleware answers before the controller", "content": { "application/json": { "schema": { "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "403": { "description": "Missing backoffice.sales.price-lists.view", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceListProblem" } } } }, "404": { "description": "price_list_not_found from the controller, or the middleware's message for an unknown company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceListNotFound404" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Backoffice - Sales - Price Lists" ], "summary": "Edit a price list", "description": "Rewrites the code, the name and the validity; the currency must be the list's own. An edit that changes nothing still answers 200 and records nothing.", "operationId": "08b79b14ac7612bf46df51181a1d18de", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "priceListId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceListUpdateRequest" } } } }, "responses": { "200": { "description": "Price list edited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceListWriteResponse" } } } }, "401": { "description": "Unauthenticated: the auth middleware answers before the controller", "content": { "application/json": { "schema": { "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "403": { "description": "Missing backoffice.sales.price-lists.manage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceListProblem" } } } }, "404": { "description": "price_list_not_found from the controller, or the middleware's message for an unknown company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceListNotFound404" } } } }, "409": { "description": "price_list_code_already_exists with field_errors.code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceListProblem" } } } }, "422": { "description": "Request validation failed, or price_list_currency_cannot_change (with price_list_currency), price_list_code_invalid, price_list_name_invalid, price_list_currency_not_supported or price_list_valid_to_before_valid_from with field_errors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceListRefusal422" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/price-lists/{priceListId}/imports/{importId}": { "get": { "tags": [ "Backoffice - Sales - Price Lists" ], "summary": "Show a price import's status", "description": "The import's status, its counts and the reason of each rejected row, in file order. A completed import may carry row errors; a failed one imported no row, and its errors are either one per row or one whole-file reason with every count at 0. The upload imports at once, so the first read is normally final. Another list's or another company's import is not found.", "operationId": "650d5fcb8f1b45f62d021f5d71e95024", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "priceListId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "importId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The import's status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceListImportStatus" } } } }, "401": { "description": "Unauthenticated: the auth middleware answers before the controller", "content": { "application/json": { "schema": { "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "403": { "description": "Missing backoffice.sales.price-lists.view", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceListProblem" } } } }, "404": { "description": "price_list_import_not_found from the controller, or the middleware's message for an unknown company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceListNotFound404" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/price-lists/{priceListId}/imports": { "post": { "tags": [ "Backoffice - Sales - Price Lists" ], "summary": "Import a price list's prices from an Excel file", "description": "Uploads an Excel file filled from the template (columns «Código del artículo», «Cantidad mínima» and «Precio», at most 5,000 rows) and imports it at once. Each row creates or updates the list's price for its item and minimum quantity (blank is 1), in the list's currency with up to 2 decimals; nothing is deleted. A row with an unknown code, an inactive item without a price, an invalid quantity or price, or repeated in the file is reported by its row number while the others import. The answer is always 202 with the import's id once the file is taken: a file that cannot be imported whole (unreadable, without the template's columns, without rows, or over 5,000 rows) reads failed in its status. Requires backoffice.sales.price-lists.manage.", "operationId": "b68e073577812f8e6092a4e545efba97", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "priceListId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "file" ], "properties": { "file": { "description": "The price file: xlsx or xls, both by MIME type and by extension, at most 5120 KB.", "type": "string", "format": "binary" } }, "type": "object" } } } }, "responses": { "202": { "description": "The file was taken and imported; read the import's status for what each row did", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceListImportAccepted" } } } }, "401": { "description": "Unauthenticated: the auth middleware answers before the controller", "content": { "application/json": { "schema": { "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "403": { "description": "Missing backoffice.sales.price-lists.manage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceListProblem" } } } }, "404": { "description": "price_list_not_found from the controller, or the middleware's message for an unknown company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceListNotFound404" } } } }, "422": { "description": "Request validation failed: errors.file when the file is missing, is not an xlsx or xls file, or exceeds 5120 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceListRefusal422" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/price-lists/import-template": { "get": { "tags": [ "Backoffice - Sales - Price Lists" ], "summary": "Download the price import template", "description": "An Excel file with a «Plantilla» sheet holding the three columns the import reads («Código del artículo», «Cantidad mínima», «Precio») and no example row, and an «Instrucciones» sheet with the import's rules.", "operationId": "225d1ff64f2fe2f9d8e0c53fe59c3ef0", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The template, as an attachment named plantilla-importacion-precios.xlsx", "headers": { "Content-Disposition": { "description": "Always this file name", "schema": { "type": "string", "example": "attachment; filename=\"plantilla-importacion-precios.xlsx\"" } }, "Cache-Control": { "description": "Always no-store: the workbook is never cached", "schema": { "type": "string", "example": "no-store, private" } } }, "content": { "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Unauthenticated: the auth middleware answers before the controller", "content": { "application/json": { "schema": { "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "403": { "description": "Problem JSON, title Forbidden. Without backoffice.sales.price-lists.view the route can: middleware answers with error_code and errors null; the tenant middleware stack (API-key guardrails, company access, tenant membership) answers without error_code, with a reason only from tenant membership.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ImportTemplateProblem" }, { "$ref": "#/components/schemas/ImportTemplateMiddlewareForbidden" } ] } } } }, "500": { "description": "Unexpected failure, reported. Problem JSON with error_code and errors null; the detail is generic in production.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportTemplateProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/price-lists": { "get": { "tags": [ "Backoffice - Sales - Price Lists" ], "summary": "List price lists", "description": "A page of the company's price lists. meta.counts holds every status under the same filters but the status one.", "operationId": "9e483a5d8e46467d0a8f14a4b7e6699b", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "search", "in": "query", "description": "Matches part of the code or the name.", "required": false, "schema": { "type": "string", "maxLength": 100 } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "active", "inactive" ] } }, { "name": "sort_by", "in": "query", "required": false, "schema": { "type": "string", "default": "code", "enum": [ "code", "name", "created_at" ] } }, { "name": "sort_order", "in": "query", "required": false, "schema": { "type": "string", "default": "asc", "enum": [ "asc", "desc" ] } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 25, "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "Price lists found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceListList" } } } }, "401": { "description": "Unauthenticated: the auth middleware answers before the controller", "content": { "application/json": { "schema": { "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "403": { "description": "Missing backoffice.sales.price-lists.view", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceListProblem" } } } }, "422": { "description": "Request validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceListProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Sales - Price Lists" ], "summary": "Create a price list", "description": "Creates a «Lista de precios», active, in USD or VES with an optional validity. Its code is unique per company.", "operationId": "998e11a13c8228cccd98d9c6d1c785bb", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceListCreateRequest" } } } }, "responses": { "201": { "description": "Price list created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceListWriteResponse" } } } }, "401": { "description": "Unauthenticated: the auth middleware answers before the controller", "content": { "application/json": { "schema": { "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "403": { "description": "Missing backoffice.sales.price-lists.manage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceListProblem" } } } }, "409": { "description": "price_list_id_already_taken, or price_list_code_already_exists with field_errors.code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceListProblem" } } } }, "422": { "description": "Request validation failed, or price_list_code_invalid, price_list_name_invalid, price_list_currency_not_supported or price_list_valid_to_before_valid_from with field_errors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceListRefusal422" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/prices/resolve": { "post": { "tags": [ "Backoffice - Sales - Price Lists" ], "summary": "Resolve the sale price of each line", "description": "Resolves, per one unit of each line's unit, the price of the list's entry with the highest minimum quantity its base quantity reaches when the list applies on the day (active and inside its validity), otherwise the item's Precio base. An entry of minimum exactly 1 is reached by any base quantity above 0 at four decimals, fractions included, and any other minimum from that many base units on (ADR 0374). It converts it to the requested currency at the document rate of the day (the first value date on or after it, ADR 0143) and rounds it half-up once. Each priced line carries its fingerprint (ADR 0272). Nothing is written: the operation only reads, accepts no query parameters and answers 200, not 201. Readable with any of backoffice.sales.sales-orders.create, backoffice.sales.sales-orders.update, backoffice.sales.sales-invoices.create, backoffice.sales.sales-invoices.update, backoffice.sales.price-lists.view, backoffice.sales.sales-quotes.create or backoffice.sales.sales-quotes.update (a registered multi-permission carve-out), checked before the body is validated. A channel_id instead of a price_list_id (never both) prices the lines from that Canal's default list, or from the Precio base when it names none; an inactive channel still resolves, and a price it chooses carries the channel in its fingerprint. A price_list_id or a channel_id also needs backoffice.sales.price-lists.view, backoffice.sales.sales-quotes.create or backoffice.sales.sales-quotes.update, checked before the list or the channel is looked up. It answers only the lines sent, and a list that does not apply on the day never exposes its prices.", "operationId": "b1a490e9d8f0d1cb9237fcc2d932de11", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalePriceResolveRequest" } } } }, "responses": { "200": { "description": "Each line's resolution, in request order", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalePriceResolution" } } } }, "401": { "description": "Unauthenticated: the auth middleware answers before the controller", "content": { "application/json": { "schema": { "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "403": { "description": "None of the seven permissions; or a price_list_id or a channel_id without backoffice.sales.price-lists.view, backoffice.sales.sales-quotes.create or backoffice.sales.sales-quotes.update, whether the list or the channel exists or not; or, before the controller, a caller who does not belong to the company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalePriceResolution403" } } } }, "404": { "description": "price_list_not_found: an unknown list or another company's; sales_channel_not_found: an unknown channel or another company's; or the middleware's message for an unknown company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceListNotFound404" } } } }, "422": { "description": "Request validation failed, a channel_id beside a price_list_id included (on channel_id); or sale_price_line_unit_not_of_item with field_errors on every lines.N.unit_id whose unit is not its item's, or whose item is not in the catalog", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalePriceResolutionRefusal422" } } } }, "500": { "description": "Unexpected, reported: for example company books outside USD and VES, a line item whose stored Precio base is half set, or a channel naming a list its company does not hold", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceListProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/clients/{id}/statement/export": { "get": { "tags": [ "Sales Receivables" ], "summary": "Exportar estado de cuenta del cliente", "operationId": "eb041ea74838c72ae6c3c43b65414af1", "parameters": [ { "name": "tenant", "in": "path", "description": "Company UUID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "Client UUID belonging to the tenant", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/ClientStatementFrom" }, { "$ref": "#/components/parameters/ClientStatementTo" }, { "$ref": "#/components/parameters/ClientStatementCurrency" } ], "responses": { "200": { "description": "Numeric XLSX attachment estado_cuenta_{client code}_{from}_{to}.xlsx titled as an informational document, with the JSON sections, lines and open credits, when every absolute amount is at most 9999999999999.99 and serialization preserves cents; otherwise 422", "headers": { "Cache-Control": { "description": "Always no-store: the workbook is never cached", "schema": { "type": "string", "example": "no-store, private" } } }, "content": { "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Unauthenticated before controller execution", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientStatementMessageError" } } } }, "403": { "description": "Receivables permission or tenant membership denied", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ClientStatementForbiddenError" }, { "$ref": "#/components/schemas/ClientStatementProblem" } ] } } } }, "404": { "description": "Tenant middleware or controller company not found; client_not_found for an unknown client or a client of another company", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ClientStatementMessageError" }, { "$ref": "#/components/schemas/ClientStatementProblem" } ] } } } }, "422": { "description": "FormRequest validation of a malformed client id, a missing or malformed from or to, a to before from, or a currency outside the enum; client_statement_invalid_period and invalid_currency from the domain as fallbacks; unsafe numeric XLSX amounts return client_statement_excel_precision_exceeded before any attachment", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ClientStatementValidationError" }, { "$ref": "#/components/schemas/ClientStatementProblem" } ] } } } }, "503": { "description": "client_statement_query_failed: the statement query is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientStatementProblem" } } } }, "500": { "description": "client_statement_invalid_data or an unexpected internal failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientStatementProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/clients/{id}/statement": { "get": { "tags": [ "Sales Receivables" ], "summary": "Estado de cuenta del cliente", "operationId": "4746bde8d7191e5a8d09fb5e4ffcd686", "parameters": [ { "name": "tenant", "in": "path", "description": "Company UUID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "Client UUID belonging to the tenant", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/ClientStatementFrom" }, { "$ref": "#/components/parameters/ClientStatementTo" }, { "$ref": "#/components/parameters/ClientStatementCurrency" } ], "responses": { "200": { "description": "Exact decimal statement; no sections when the client has no movement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientStatement" } } } }, "401": { "description": "Unauthenticated before controller execution", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientStatementMessageError" } } } }, "403": { "description": "Receivables permission or tenant membership denied", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ClientStatementForbiddenError" }, { "$ref": "#/components/schemas/ClientStatementProblem" } ] } } } }, "404": { "description": "Tenant middleware or controller company not found; client_not_found for an unknown client or a client of another company", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ClientStatementMessageError" }, { "$ref": "#/components/schemas/ClientStatementProblem" } ] } } } }, "422": { "description": "FormRequest validation of a malformed client id, a missing or malformed from or to, a to before from, or a currency outside the enum; client_statement_invalid_period and invalid_currency from the domain as fallbacks", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ClientStatementValidationError" }, { "$ref": "#/components/schemas/ClientStatementProblem" } ] } } } }, "503": { "description": "client_statement_query_failed: the statement query is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientStatementProblem" } } } }, "500": { "description": "client_statement_invalid_data or an unexpected internal failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientStatementProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/receivables/aging/export": { "get": { "tags": [ "Sales Receivables" ], "summary": "Exportar antigüedad de cuentas por cobrar", "operationId": "af035228a35d8a2d4ee2177af640404a", "parameters": [ { "name": "tenant", "in": "path", "description": "Company UUID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/ReceivablesAgingClient" }, { "$ref": "#/components/parameters/ReceivablesAgingCurrency" }, { "$ref": "#/components/parameters/ReceivablesAgingCenter" } ], "responses": { "200": { "description": "Numeric XLSX attachment antiguedad_cxc_{as_of}.xlsx with the JSON rows, currency totals and book totals when every absolute amount is at most 9999999999999.99 and serialization preserves cents; otherwise 422", "headers": { "Cache-Control": { "description": "Always no-store: the workbook is never cached", "schema": { "type": "string", "example": "no-store, private" } } }, "content": { "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Unauthenticated before controller execution", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReceivablesAgingMessageError" } } } }, "403": { "description": "Receivables permission or tenant membership denied", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ReceivablesAgingForbiddenError" }, { "$ref": "#/components/schemas/ReceivablesAgingProblem" } ] } } } }, "404": { "description": "An unknown company in the path, answered by the tenant middleware with a message, or company_not_found when the report cannot read the company's record", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReceivablesAgingMessageError" }, { "$ref": "#/components/schemas/ReceivablesAgingProblem" } ] } } } }, "422": { "description": "FormRequest validation of a malformed or foreign client or accounting center, or a currency outside the enum; invalid_currency from the domain as a fallback; unsafe numeric XLSX amounts return receivables_aging_excel_precision_exceeded before any attachment", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReceivablesAgingValidationError" }, { "$ref": "#/components/schemas/ReceivablesAgingProblem" } ] } } } }, "503": { "description": "receivables_aging_query_failed: the aging query is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReceivablesAgingProblem" } } } }, "500": { "description": "receivables_aging_invalid_data, an unexpected internal failure, or a tenant route that lost its company (TenantCompanyMissing)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReceivablesAgingProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/receivables/aging": { "get": { "tags": [ "Sales Receivables" ], "summary": "Antigüedad de cuentas por cobrar", "operationId": "05bcbf19fdead6eb978fd37d97346e54", "parameters": [ { "name": "tenant", "in": "path", "description": "Company UUID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/ReceivablesAgingClient" }, { "$ref": "#/components/parameters/ReceivablesAgingCurrency" }, { "$ref": "#/components/parameters/ReceivablesAgingCenter" } ], "responses": { "200": { "description": "Exact decimal aging as of today; empty rows and 0.00 totals when nothing is open", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReceivablesAging" } } } }, "401": { "description": "Unauthenticated before controller execution", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReceivablesAgingMessageError" } } } }, "403": { "description": "Receivables permission or tenant membership denied", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ReceivablesAgingForbiddenError" }, { "$ref": "#/components/schemas/ReceivablesAgingProblem" } ] } } } }, "404": { "description": "An unknown company in the path, answered by the tenant middleware with a message, or company_not_found when the report cannot read the company's record", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReceivablesAgingMessageError" }, { "$ref": "#/components/schemas/ReceivablesAgingProblem" } ] } } } }, "422": { "description": "FormRequest validation of a malformed or foreign client or accounting center, or a currency outside the enum; invalid_currency from the domain as a fallback", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReceivablesAgingValidationError" }, { "$ref": "#/components/schemas/ReceivablesAgingProblem" } ] } } } }, "503": { "description": "receivables_aging_query_failed: the aging query is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReceivablesAgingProblem" } } } }, "500": { "description": "receivables_aging_invalid_data, an unexpected internal failure, or a tenant route that lost its company (TenantCompanyMissing)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReceivablesAgingProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/sales-channels/{salesChannelId}/keys": { "get": { "tags": [ "Backoffice - Sales - Storefront Keys" ], "summary": "List Claves de Vitrina for a sales channel", "operationId": "aa5013b18d8dbcbacb7fdd3e5cd3e3ab", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "salesChannelId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Keys for the channel (no secrets)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorefrontKeysListResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "403": { "description": "Missing backoffice.sales.sales-channels.manage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorefrontKeyProblem" } } } }, "404": { "description": "sales_channel_not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorefrontKeyProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Sales - Storefront Keys" ], "summary": "Issue a Clave de Vitrina", "operationId": "0cb7e6ef7030c52ebe96f7b357485450", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "salesChannelId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorefrontKeyIssueRequest" } } } }, "responses": { "201": { "description": "Key issued; plaintext secret returned once", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorefrontKeyIssueResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "403": { "description": "Missing backoffice.sales.sales-channels.manage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorefrontKeyProblem" } } } }, "404": { "description": "sales_channel_not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorefrontKeyProblem" } } } }, "409": { "description": "storefront_key_id_already_taken or storefront_key_limit_reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorefrontKeyProblem" } } } }, "422": { "description": "Validation or channel gate refusal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorefrontKeyProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/sales-channels/{salesChannelId}/keys/{keyId}/revocation": { "put": { "tags": [ "Backoffice - Sales - Storefront Keys" ], "summary": "Revoke a Clave de Vitrina", "operationId": "b3b47a1e752244264d3f2c6855732e83", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "salesChannelId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "keyId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Key revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorefrontKeyView" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "403": { "description": "Missing backoffice.sales.sales-channels.manage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorefrontKeyProblem" } } } }, "404": { "description": "storefront_key_not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorefrontKeyProblem" } } } }, "409": { "description": "storefront_key_already_revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorefrontKeyProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/sales-channels/{salesChannelId}/items/{itemId}/publication": { "put": { "tags": [ "Backoffice - Sales - Sales Channels" ], "summary": "Publish an item in a storefront sales channel", "operationId": "90590cec6d005613946ade93796e85b4", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "salesChannelId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "itemId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Publication created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemPublicationWriteResponse" } } } }, "200": { "description": "Already published", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemPublicationWriteResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "403": { "description": "Missing backoffice.sales.sales-channels.publish", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemPublicationProblem" } } } }, "404": { "description": "sales_channel_not_found or item_not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemPublicationNotFound404" } } } }, "422": { "description": "Publication guard refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemPublicationRefusal422" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Backoffice - Sales - Sales Channels" ], "summary": "Unpublish an item from a sales channel", "operationId": "cbdd6cfa0f26f6d12e98b14481727cd3", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "salesChannelId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "itemId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Unpublished or already unpublished" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "403": { "description": "Missing backoffice.sales.sales-channels.publish", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemPublicationProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/item-publications": { "get": { "tags": [ "Backoffice - Sales - Sales Channels" ], "summary": "List publications of an item across sales channels", "operationId": "638010c887e3d06c7cd0ee5ec5cdd4e1", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "item_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Publications of the item", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemPublicationList" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "403": { "description": "Missing backoffice.sales.sales-channels.view", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemPublicationProblem" } } } }, "422": { "description": "item_id missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemPublicationProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/sales-channels/{salesChannelId}/activation": { "put": { "tags": [ "Backoffice - Sales - Sales Channels" ], "summary": "Activate a sales channel", "operationId": "f7fd84ff75fe804d1541f6b85d037791", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "salesChannelId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Sales channel activated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesChannelWriteResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "403": { "description": "Missing backoffice.sales.sales-channels.manage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesChannelProblem" } } } }, "404": { "description": "sales_channel_not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesChannelNotFound404" } } } }, "409": { "description": "sales_channel_status_transition_not_allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesChannelProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/sales-channels/{salesChannelId}/deactivation": { "put": { "tags": [ "Backoffice - Sales - Sales Channels" ], "summary": "Deactivate a sales channel", "operationId": "11a615c61326a36fbf1817d317280a12", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "salesChannelId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Sales channel deactivated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesChannelWriteResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "403": { "description": "Missing backoffice.sales.sales-channels.manage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesChannelProblem" } } } }, "404": { "description": "sales_channel_not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesChannelNotFound404" } } } }, "409": { "description": "sales_channel_status_transition_not_allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesChannelProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/sales-channels/{salesChannelId}": { "get": { "tags": [ "Backoffice - Sales - Sales Channels" ], "summary": "Show a sales channel", "operationId": "4a10fc2c9d28ace138ae240ae62df8d2", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "salesChannelId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Sales channel found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesChannel" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "403": { "description": "Missing backoffice.sales.sales-channels.view", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesChannelProblem" } } } }, "404": { "description": "sales_channel_not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesChannelNotFound404" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Backoffice - Sales - Sales Channels" ], "summary": "Edit a sales channel", "description": "Rewrites name, location, default list, origins, umbral and URL de revalidación. Code and kind stay as created. An omitted low_stock_threshold or revalidation_url keeps the stored one.", "operationId": "d8ab62de074718f617b9d52607dd6b52", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "salesChannelId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesChannelUpdateRequest" } } } }, "responses": { "200": { "description": "Sales channel edited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesChannelWriteResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "403": { "description": "Missing backoffice.sales.sales-channels.manage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesChannelProblem" } } } }, "404": { "description": "sales_channel_not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesChannelNotFound404" } } } }, "422": { "description": "Validation or domain refusal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesChannelRefusal422" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/sales-channels": { "get": { "tags": [ "Backoffice - Sales - Sales Channels" ], "summary": "List sales channels", "operationId": "70a6fde98d11bc5e73cb21394c20ed30", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 100 } }, { "name": "kind", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pos", "storefront" ] } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "active", "inactive" ] } }, { "name": "sort_by", "in": "query", "required": false, "schema": { "type": "string", "default": "code", "enum": [ "code", "name", "created_at" ] } }, { "name": "sort_order", "in": "query", "required": false, "schema": { "type": "string", "default": "asc", "enum": [ "asc", "desc" ] } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 25, "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "Sales channels found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesChannelList" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "403": { "description": "Missing backoffice.sales.sales-channels.view", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesChannelProblem" } } } }, "422": { "description": "Request validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesChannelProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Sales - Sales Channels" ], "summary": "Create a sales channel", "description": "Creates a «Canal», active, with a location, optional default list and storefront origins.", "operationId": "3402413cfe54f86be26f0be0229ee35d", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesChannelCreateRequest" } } } }, "responses": { "201": { "description": "Sales channel created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesChannelWriteResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "403": { "description": "Missing backoffice.sales.sales-channels.manage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesChannelProblem" } } } }, "409": { "description": "sales_channel_id_already_taken or sales_channel_code_already_exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesChannelProblem" } } } }, "422": { "description": "Validation or domain refusal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesChannelRefusal422" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/sales-channels/{salesChannelId}/publications": { "get": { "tags": [ "Backoffice - Sales - Sales Channels" ], "summary": "List items published in a sales channel", "operationId": "4f4adea78ce6c1c6a8edc73758797517", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "salesChannelId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 100 } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 25, "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "Published items in the channel", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelItemPublicationList" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "403": { "description": "Missing backoffice.sales.sales-channels.view", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemPublicationProblem" } } } }, "404": { "description": "sales_channel_not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemPublicationNotFound404" } } } }, "422": { "description": "Request validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemPublicationProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Sales - Sales Channels" ], "summary": "Publish many items in a storefront sales channel", "operationId": "a502f41190fac561ee2035d40893c969", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "salesChannelId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemBatchPublicationRequest" } } } }, "responses": { "200": { "description": "Per-item publish outcomes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemBatchPublishResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "403": { "description": "Missing backoffice.sales.sales-channels.publish", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemPublicationProblem" } } } }, "404": { "description": "sales_channel_not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemPublicationNotFound404" } } } }, "422": { "description": "Validation failed or channel refused the batch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemBatchPublicationRefusal422" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/sales-channels/{salesChannelId}/revalidation-secret": { "post": { "tags": [ "Backoffice - Sales - Sales Channels" ], "summary": "Rotate a storefront's revalidation secret", "description": "Generates a new Secreto de revalidación for a storefront channel (MER-4193) and replaces the previous one. The plaintext is returned only in this response; every call rotates again.", "operationId": "bd02aa82a091354fcb114d4623b31c06", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "salesChannelId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Secret generated; plaintext returned once", "headers": { "Cache-Control": { "description": "Always no-store: the secret must never be cached.", "schema": { "type": "string", "example": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesChannelRevalidationSecretResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "403": { "description": "Missing backoffice.sales.sales-channels.manage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesChannelProblem" } } } }, "404": { "description": "sales_channel_not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesChannelNotFound404" } } } }, "422": { "description": "revalidation_not_allowed_for_pos", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesChannelRefusal422" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/sales-channels/{salesChannelId}/unpublications": { "post": { "tags": [ "Backoffice - Sales - Sales Channels" ], "summary": "Unpublish many items from a sales channel", "operationId": "7b40b35ff22595f28156e161edd035d3", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "salesChannelId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemBatchPublicationRequest" } } } }, "responses": { "200": { "description": "Per-item unpublish outcomes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemBatchUnpublishResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "403": { "description": "Missing backoffice.sales.sales-channels.publish", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemPublicationProblem" } } } }, "404": { "description": "sales_channel_not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemPublicationNotFound404" } } } }, "422": { "description": "Validation failed or channel refused the batch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemBatchPublicationRefusal422" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/sales-invoices/lookup": { "get": { "tags": [ "Backoffice - Sales - Invoice Lookups" ], "summary": "Invoice labels for tenant form selectors and filters", "operationId": "f61dc2b0cc62de893072c92a0557c7d9", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "search", "in": "query", "schema": { "type": "string", "maxLength": 100 } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "maximum": 200, "minimum": 1 } } ], "responses": { "200": { "description": "Minimal invoice labels; no amounts or audit metadata", "content": { "application/json": { "schema": { "required": [ "items", "total", "per_page", "current_page" ], "properties": { "items": { "type": "array", "items": { "required": [ "id", "code" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" } }, "type": "object" } }, "total": { "type": "integer" }, "per_page": { "type": "integer" }, "current_page": { "type": "integer" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Not a tenant member" }, "404": { "description": "Tenant not found" }, "422": { "description": "Invalid pagination" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/sales-invoices/{id}/contingency-report": { "put": { "tags": [ "Sales" ], "summary": "Record when a contingency PDF was reported", "operationId": "reportSalesInvoicesContingency", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "reported_on" ], "properties": { "reported_on": { "type": "string", "format": "date", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Recorded without accounting changes" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Approve permission required" }, "404": { "description": "Document not found in this company/kind" }, "422": { "description": "Invalid date, date before emission, or document outside digital contingency reporting. Validation: message/errors; domain: error_code/detail." }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/credit-notes/{id}/contingency-report": { "put": { "tags": [ "Sales" ], "summary": "Record when a contingency PDF was reported", "operationId": "reportCreditNotesContingency", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "reported_on" ], "properties": { "reported_on": { "type": "string", "format": "date", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Recorded without accounting changes" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Approve permission required" }, "404": { "description": "Document not found in this company/kind" }, "422": { "description": "Invalid date, date before emission, or document outside digital contingency reporting. Validation: message/errors; domain: error_code/detail." }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/debit-notes/{id}/contingency-report": { "put": { "tags": [ "Sales" ], "summary": "Record when a contingency PDF was reported", "operationId": "reportDebitNotesContingency", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "reported_on" ], "properties": { "reported_on": { "type": "string", "format": "date", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Recorded without accounting changes" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Approve permission required" }, "404": { "description": "Document not found in this company/kind" }, "422": { "description": "Invalid date, date before emission, or document outside digital contingency reporting. Validation: message/errors; domain: error_code/detail." }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/sales-invoices/{id}/accounting-readiness": { "get": { "tags": [ "Backoffice - Sales Invoices" ], "summary": "Get accounting readiness for a sales invoice", "operationId": "0a87a506165d5d6bd2c03a5a2c62e7a4", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Accounting readiness snapshot", "content": { "application/json": { "schema": { "properties": { "ready": { "type": "boolean" }, "missing": { "type": "array", "items": { "properties": { "reason_code": { "type": "string" }, "subject_type": { "type": "string" }, "subject_id": { "type": "string" }, "human_message": { "type": "string" }, "details": { "type": "array", "items": { "type": "string" } } }, "type": "object" } }, "warnings": { "$ref": "#/components/schemas/AccountingReadinessWarnings" } }, "type": "object" } } } }, "403": { "description": "Unauthorized" }, "404": { "description": "Sales invoice not found, or an id that is not a UUID, which the router answers before the controller with a `message` body." }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/sales-invoices/{id}/approve": { "post": { "tags": [ "Backoffice - Sales Invoices" ], "summary": "Approve a sales invoice", "operationId": "9e8540c619bcd78fd54389e61e60aab2", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "financial_fingerprint": { "description": "Optional SHA-256 of the current stored-versus-recalculated comparison. Required only when those amounts differ.", "type": "string", "pattern": "^[a-f0-9]{64}$", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Sales invoice approved successfully" }, "403": { "description": "Unauthorized" }, "404": { "description": "Sales invoice not found, or an id that is not a UUID, which the router answers before the controller with a `message` body." }, "409": { "description": "Sales invoice cannot be modified in current status, Disponible does not cover every line while reserving on approval is switched on (insufficient_stock), or the advance invoice a balance invoice deducts was applied, credited or cancelled since it was drafted (advance_invoice_not_pending, with advance_invoice_id and advance_invoice_status: of two approvals deducting one advance invoice, the second receives it)", "content": { "application/json": { "schema": { "oneOf": [ { "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "detail": { "type": "string" }, "error_code": { "type": "string", "example": "sales_invoice_cannot_be_modified" }, "errors": { "type": "object", "example": null, "nullable": true }, "advance_invoice_id": { "description": "Only on advance_invoice_not_pending.", "type": "string", "format": "uuid" }, "advance_invoice_status": { "description": "Only on advance_invoice_not_pending.", "type": "string", "enum": [ "applied", "credited", "cancelled" ] } }, "type": "object" }, { "$ref": "#/components/schemas/InsufficientStockProblem" } ] } } } }, "422": { "description": "advance_invoice_withholding_agent_not_supported for declared client VAT or ISLR withholding agents; advance_invoice_no_service, keyed by advance_collection_id, for an Advance whose purpose is no_service; Stored amounts require acceptance, the supplied fingerprint is stale, readiness blocks approval (a balance invoice also needs the customer_advances role: CUSTOMER_ADVANCES_ACCOUNT_MISSING), an advance invoice or a balance invoice deducting one belongs to a frozen fiscal day (document_in_frozen_fiscal_period), the advance invoice a balance invoice deducts no longer qualifies or would leave nothing to collect (advance_deduction_invalid with `reason`), the frozen totals value to 0.00 in both books (document_values_to_zero_in_both_books), or an invoice of a sales order is worth more than what the order has left to bill plus a rounding cent per approved invoice (sales_order_invoice_exceeds_balance).", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string" }, "status": { "type": "integer", "example": 422 }, "error_code": { "type": "string", "nullable": true }, "errors": { "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "reason": { "description": "Only on advance_deduction_invalid.", "type": "string", "enum": [ "advance_invoice_not_found", "advance_invoice_not_approved", "customer_mismatch", "currency_mismatch", "date_after_invoice", "advance_balance_differs_from_base", "advance_covers_whole_invoice" ] }, "fiscal_period": { "$ref": "#/components/schemas/FrozenFiscalPeriod" }, "error": { "type": "string", "example": "sales_invoice_historical_difference_acceptance_required" }, "detail": { "type": "string" }, "financial_fingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "previous": { "properties": { "subtotal": { "type": "string", "example": "1.00" }, "discount": { "type": "string", "example": "0.00" }, "taxes": { "type": "string", "example": "0.00" }, "total": { "type": "string", "example": "1.00" } }, "type": "object" }, "proposed": { "properties": { "subtotal": { "type": "string", "example": "10.00" }, "discount": { "type": "string", "example": "0.12" }, "taxes": { "type": "string", "example": "0.00" }, "total": { "type": "string", "example": "9.88" } }, "type": "object" } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/sales-invoices/{id}/cancel": { "post": { "tags": [ "Backoffice - Sales Invoices" ], "summary": "Cancel a sales invoice", "description": "Cancel a sales invoice that has no collections applied. An invoice the current Declared Set of a Fiscal Period in review or closed holds is rejected first with 409 document_in_frozen_fiscal_period, naming the period in `fiscal_period`; once the period returns to open it cancels as usual (MER-3837). An invoice with credit or debit notes that are not cancelled, drafts included, is rejected with 409 sales_invoice_has_live_notes naming them in `notes`, checked before its collections; once its notes are cancelled it cancels as usual. An invoice a received VAT withholding relieved (`withheld_amount` above zero) is rejected with 409 sales_invoice_has_received_withholding, checked after its collections (MER-3692). A direct invoice whose inventory dispatch is still pending cascades the cancellation to that dispatch; an invoice whose dispatch already released stock (partial or completed) is rejected with 409.", "operationId": "d9e40b5fdf30dd01830ff76501d7682d", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Sales invoice cancelled successfully" }, "400": { "description": "Missing company context" }, "403": { "description": "Unauthorized" }, "404": { "description": "Sales invoice not found, or an id that is not a UUID, which the router answers before the controller with a `message` body." }, "409": { "description": "Sales invoice cannot be cancelled: a frozen fiscal period declared it (error_code document_in_frozen_fiscal_period, with `fiscal_period`), it has notes that are not cancelled, drafts included (error_code sales_invoice_has_live_notes, with `notes` in id order), it has collections applied (error_code sales_invoice_cannot_be_cancelled), a received withholding relieved it (error_code sales_invoice_has_received_withholding), or its inventory dispatch already released stock (error_code sales_invoice_has_warehouse_exit)", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "detail": { "type": "string", "example": "La factura INV2600012 tiene notas vigentes (NC2600001, NC2600002). Para cancelarla, primero cancela esas notas." }, "error_code": { "type": "string", "example": "sales_invoice_has_live_notes", "enum": [ "document_in_frozen_fiscal_period", "sales_invoice_has_live_notes", "sales_invoice_cannot_be_cancelled", "sales_invoice_has_received_withholding", "sales_invoice_has_warehouse_exit", "advance_invoice_in_use" ] }, "errors": { "type": "object", "nullable": true }, "notes": { "description": "Only on sales_invoice_has_live_notes: the notes to cancel first.", "type": "array", "items": { "$ref": "#/components/schemas/SalesInvoiceLiveNote" } }, "fiscal_period": { "description": "Only on document_in_frozen_fiscal_period: the period whose current Declared Set holds the document.", "allOf": [ { "$ref": "#/components/schemas/FrozenFiscalPeriod" } ] } }, "type": "object" } } } }, "422": { "description": "An advance invoice's fiscal day, or that of a balance invoice deducting one (MER-4263), is in review or closed (document_in_frozen_fiscal_period), its source is unavailable, or its reversal cannot be posted. Other regular invoices retain the documented 409 frozen-period response. Cancelling an approved balance invoice gives its advance back exactly what its approval took and makes its advance invoice advance_pending again.", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string" }, "status": { "type": "integer", "example": 422 }, "error_code": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "fiscal_period": { "$ref": "#/components/schemas/FrozenFiscalPeriod" } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/sales-invoices/{id}/credit-applications": { "get": { "tags": [ "Backoffice - Sales Invoices" ], "summary": "List the credit applications that relieved a sales invoice", "description": "Every credit-note and customer-advance application that relieved the sales invoice, live and reverted, by date then the order they were recorded (MER-4718). An invoice is relieved by a bounded number of applications, so the list is not paginated. Unapply stays at the source; this endpoint is read-only. Requires backoffice.sales.sales-invoices.view.", "operationId": "listSalesInvoiceCreditApplications", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The invoice's relieving applications, empty when it has none", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesCreditApplicationList" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks backoffice.sales.sales-invoices.view" }, "404": { "description": "sales_invoice_not_found: the invoice does not exist or belongs to another company, also for a note or debit id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesCreditApplicationProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/sales-invoices/{id}/fiscal-identity": { "put": { "tags": [ "Backoffice - Sales Invoices" ], "summary": "Capture or correct a sales invoice's fiscal identity", "description": "Records the invoice number and control number printed on the paper this invoice represents. Allowed in every status except cancelled, so an approved invoice can still be completed or corrected. Both numbers are kept as printed (ADR 0380): surrounding whitespace is trimmed, and case, inner spaces and leading zeros are kept, so ' 00-0001 2345 ' is stored as '00-0001 2345'. What remains must be 1 to 30 letters, digits, spaces, hyphens, ° or º. A control number already held by another non-cancelled invoice or note of the same company, compared without whitespace or case (º counts as O), is rejected with 409. An invoice the current Declared Set of a Fiscal Period in review or closed holds is rejected first with 409 document_in_frozen_fiscal_period, naming the period in `fiscal_period`: its book already printed its numbers (MER-3837). It also records the serial of the fiscal machine that printed the invoice, stored apart from the control number (ADR 0261, MER-4972); the printed numbers the accounting readiness asks for depend on the invoice's issuance channel: a fiscal_machine invoice needs its invoice number and serial, never a control number.", "operationId": "0a36693e683b0eb8d960f227357995ed", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "issued_in_contingency": { "description": "Mark the document as issued in contingency; omitted preserves the stored mark.", "type": "boolean" }, "contingency_reason": { "type": "string", "nullable": true, "enum": [ "power_failure", "internet_outage", "equipment_failure", "unplanned_maintenance", "fiscal_machine_unable", "third_party", "export", "multiple_copies", "other" ] }, "contingency_note": { "description": "Required for other cause.", "type": "string", "nullable": true, "maxLength": 500 }, "invoice_number": { "description": "The fiscal invoice number as printed, trimmed and otherwise kept as typed; blank means absent, and an omitted key is stored as absent too: the pair is replaced together.", "type": "string", "example": "00-001234", "nullable": true, "maxLength": 60 }, "control_number": { "description": "The fiscal control number as printed, trimmed and otherwise kept as typed; unique among the company's non-cancelled invoices and notes, compared without whitespace or case (º counts as O). Blank means absent, and an omitted key is stored as absent too.", "type": "string", "example": "00-00012345", "nullable": true, "maxLength": 60 }, "fiscal_machine_serial": { "description": "The serial of the fiscal machine that printed the invoice (ADR 0261), canonicalized before storage, unlike the numbers: whitespace dropped, upper-cased, leading zeros kept. The canonical form is 1 to 30 characters of A-Z, 0-9 and hyphens. It is never stored as the control number. Omit the key to keep the serial the invoice holds; send null or blank to clear it.", "type": "string", "example": "Z1B-0042", "nullable": true, "maxLength": 60 } }, "type": "object" } } } }, "responses": { "200": { "description": "Fiscal identity captured successfully" }, "403": { "description": "Unauthorized" }, "404": { "description": "Sales invoice not found, or an id that is not a UUID, which the router answers before the controller with a `message` body." }, "409": { "description": "The control number already belongs to another non-cancelled invoice or note of this company (sales_invoice_control_number_already_registered), or a frozen fiscal period declared the invoice (document_in_frozen_fiscal_period, with `fiscal_period`)", "content": { "application/json": { "schema": { "properties": { "error_code": { "type": "string", "example": "sales_invoice_control_number_already_registered", "enum": [ "sales_invoice_control_number_already_registered", "document_in_frozen_fiscal_period" ] }, "detail": { "type": "string" }, "existing_code": { "description": "The code of the document, invoice or note, that already holds the control number, or null when a concurrent commit leaves the failure path unable to name it.", "type": "string", "example": "INV00001", "nullable": true }, "existing_kind": { "description": "The kind of the document that already holds the control number: invoices and notes share one control series. Null exactly when existing_code is null.", "type": "string", "example": "regular", "nullable": true, "enum": [ "regular", "opening", "credit_note", "debit_note", "advance" ] }, "fiscal_period": { "description": "Only on document_in_frozen_fiscal_period: the period whose current Declared Set holds the invoice.", "allOf": [ { "$ref": "#/components/schemas/FrozenFiscalPeriod" } ] } }, "type": "object" } } } }, "422": { "description": "The invoice is cancelled, or a number is outside its printed form or the serial outside its canonical form: for example invalid_invoice_number, invalid_control_number or invalid_fiscal_machine_serial.", "content": { "application/json": { "schema": { "properties": { "error_code": { "type": "string", "example": "invalid_fiscal_machine_serial" }, "detail": { "type": "string" } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/sales-invoices/{id}": { "get": { "tags": [ "Backoffice - Sales Invoices" ], "summary": "Get a sales invoice by ID", "description": "An invoice's detail. It reads invoices only: a credit or debit note id answers 404. It embeds the invoice's notes, what relieved it (breakdown) and the derived «Acreditada» label (is_credited), MER-3178. `notes` lists only the kinds the caller may also view (backoffice.sales.credit-notes.view, backoffice.sales.debit-notes.view): a caller with neither gets `[]`. `breakdown`, `is_credited` and `has_live_notes` are always present, whatever note permissions the caller holds. For an approved regular invoice, breakdown.collected + breakdown.withheld + breakdown.credited + breakdown.pending = total in the document currency; render the amounts as given, never derive one from the others.", "operationId": "a99cf654e38f8662af1103440a504bec", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "422": { "description": "Invalid request" }, "200": { "description": "Sales invoice details", "content": { "application/json": { "schema": { "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "sales_order_id": { "type": "string", "format": "uuid", "nullable": true }, "sales_order_code": { "type": "string", "nullable": true }, "sales_quote_id": { "description": "The sales quote the invoice was converted from (MER-3893); null for an invoice created directly or from a sales order.", "type": "string", "format": "uuid", "nullable": true }, "sales_quote_code": { "description": "The code of that sales quote; null when there is none.", "type": "string", "nullable": true }, "sales_channel_id": { "description": "The Canal (sales channel) this Comercio invoice was sold through (MER-4184, ADR 0224). Null for Backoffice documents. Distinct from issuance_channel (fiscal issuance).", "type": "string", "format": "uuid", "nullable": true }, "sales_channel_name": { "description": "The Canal name at read time; still resolved after later deactivation.", "type": "string", "nullable": true }, "responsible_user_id": { "type": "string", "nullable": true }, "responsible_user_name": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "nullable": true }, "updated_at": { "type": "string", "format": "date-time", "nullable": true }, "labels": { "type": "array", "items": { "required": [ "id", "name", "tone", "archived" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "tone": { "type": "string" }, "archived": { "type": "boolean" } }, "type": "object" } }, "price_list_id": { "type": "string", "format": "uuid", "nullable": true }, "customer_id": { "type": "string" }, "customer_name": { "type": "string", "nullable": true }, "payment_term": { "type": "string", "enum": [ "cash", "five_days", "seven_days", "fifteen_days", "thirty_days" ] }, "emission_date": { "type": "string", "format": "date" }, "accounting_center_id": { "type": "string" }, "accounting_account_receivable_id": { "type": "string" }, "receivable_account_name": { "type": "string", "nullable": true }, "location_id": { "type": "string", "nullable": true }, "status": { "description": "The stored status. An invoice settled only by credit notes stays fully_collected; is_credited tells it apart.", "type": "string" }, "advance_status": { "type": "string", "nullable": true, "enum": [ "to_be_approved", "advance_pending", "applied", "credited", "cancelled" ] }, "advance_collection": { "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "currency": { "type": "string" }, "balance": { "type": "string" }, "functional_balance": { "type": "string" }, "reporting_balance": { "type": "string" } }, "type": "object", "nullable": true }, "advance_deduction": { "description": "What this regular invoice deducts of an advance invoice (MER-4263, ADR 0295); null when it deducts nothing. subtotal − discount − deducted_base + taxes = total, and tax_summaries state the net groups. The book amounts are null until the invoice is approved.", "required": [ "advance_invoice", "tax_id", "tax_percentage", "deducted_base", "advance_invoice_vat", "deducted_functional", "deducted_reporting" ], "properties": { "advance_invoice": { "description": "The advance invoice as it reads now: a draft whose advance invoice was applied elsewhere shows it applied.", "required": [ "id", "code", "invoice_number", "control_number", "emission_date", "currency", "status" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string", "example": "FA00001" }, "invoice_number": { "type": "string", "example": "00000001", "nullable": true }, "control_number": { "type": "string", "example": "00-00000001", "nullable": true }, "emission_date": { "type": "string", "format": "date", "example": "2026-09-14" }, "currency": { "type": "string", "example": "VES", "enum": [ "USD", "VES" ] }, "status": { "type": "string", "example": "advance_pending", "enum": [ "to_be_approved", "advance_pending", "applied", "credited", "cancelled" ] } }, "type": "object" }, "tax_id": { "description": "The tax of the group the advance invoice base is deducted from.", "type": "string", "format": "uuid" }, "tax_percentage": { "type": "string", "example": "16.00" }, "deducted_base": { "description": "The advance invoice base deducted, in the document currency.", "type": "string", "example": "1000.00" }, "advance_invoice_vat": { "description": "The VAT the advance invoice already declared, for display.", "type": "string", "example": "160.00" }, "deducted_functional": { "description": "What the Advance gave up in the functional book at approval; null until approved.", "type": "string", "example": "1000.00", "nullable": true }, "deducted_reporting": { "description": "What the Advance gave up in the reporting book at approval; null until approved.", "type": "string", "example": "7.69", "nullable": true } }, "type": "object", "nullable": true }, "applied_by": { "description": "On an advance invoice: the approved balance invoice that applied it (MER-4263), derived and never stored. Null for any other invoice and while no approved balance invoice holds it.", "required": [ "id", "code", "invoice_number", "emission_date" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string", "example": "INV2600005" }, "invoice_number": { "type": "string", "example": "00000005", "nullable": true }, "emission_date": { "type": "string", "format": "date", "example": "2026-09-21" } }, "type": "object", "nullable": true }, "kind": { "description": "An opening is registered already open and settles through collections only (ADR 0179).", "type": "string", "example": "regular", "enum": [ "regular", "opening", "advance" ] }, "reference": { "type": "string", "nullable": true }, "subtotal": { "type": "string", "example": "1000.00" }, "discount": { "type": "string", "example": "0.00" }, "taxes": { "type": "string", "example": "160.00" }, "total": { "type": "string", "example": "1160.00" }, "currency": { "description": "Document currency (MER-2948); a row the backfill has not reached is read as USD.", "type": "string", "example": "VES", "enum": [ "USD", "VES" ] }, "functional_rate": { "description": "Document to functional rate, 8 decimals.", "type": "string", "example": "1.00000000" }, "functional_rate_reference": { "description": "The exchange rate the functional leg was frozen from; null for an identity leg.", "type": "string", "format": "uuid", "nullable": true }, "reporting_rate": { "description": "Functional to reporting rate, 8 decimals.", "type": "string", "example": "1.00000000" }, "reporting_rate_reference": { "description": "The exchange rate the reporting leg was frozen from; null for an identity leg.", "type": "string", "format": "uuid", "nullable": true }, "rate_rule": { "description": "Rate rule the snapshot was selected under.", "type": "string", "example": "identity" }, "rate_value_date": { "description": "Value date of the snapshot.", "type": "string", "format": "date", "example": "2026-09-23" }, "rate_known_at": { "description": "When the rate became known; null for an identity leg.", "type": "string", "format": "date-time", "nullable": true }, "rate_origin": { "description": "Where the rate came from; null for an identity leg.", "type": "string", "nullable": true }, "functional_total": { "description": "Document total valued in the functional currency; once approved, the frozen sum of the tax groups (MER-2951).", "type": "string", "example": "1160.00" }, "reporting_total": { "description": "Functional total valued in the reporting currency.", "type": "string", "example": "1160.00" }, "balance": { "description": "Open amount in the document currency; 0.00 until the invoice is approved.", "type": "string", "example": "28.40", "nullable": true }, "functional_balance": { "description": "Open amount in the functional currency; 0.00 until the invoice is approved.", "type": "string", "example": "28.40" }, "reporting_balance": { "description": "Open amount in the reporting currency; 0.00 until the invoice is approved.", "type": "string", "example": "28.40" }, "withheld_amount": { "description": "What received withholdings relieved, in the Document Currency (MER-3692); the invoice is to be collected while `balance ≥ total − withheld_amount`.", "type": "string", "example": "120.00" }, "observations": { "type": "string", "nullable": true }, "company_id": { "type": "string", "format": "uuid" }, "dispatch": { "description": "Despacho de Inventario de la factura. null cuando la factura no tiene despacho propio: nacida de una orden de venta, aún sin aprobar, o sin salida de almacén asociada.", "required": [ "id", "code", "status" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string", "example": "ID2600034" }, "status": { "type": "string", "example": "pending", "enum": [ "pending", "partial", "completed", "cancelled", "closed_short" ] } }, "type": "object", "nullable": true }, "invoice_number": { "description": "The invoice number printed on the paper the invoice represents (MER-2950), kept as printed: trimmed, with case, inner spaces and leading zeros kept (ADR 0380). Null until captured.", "type": "string", "example": "00-001234", "nullable": true }, "control_number": { "description": "The control number printed on that paper (MER-2950, ADR 0162). Null until captured; a fiscal machine prints none, so a fiscal_machine invoice is never asked for one (ADR 0261, MER-4972).", "type": "string", "example": "00-00012345", "nullable": true }, "issuance_channel": { "description": "The Issuance Channel the invoice was written under, snapshotted from the company fiscal profile on every create, edit and capture (MER-2950): for example fiscal_machine, free_form or digital_printer. Null when the company had no fiscal profile. It decides which printed numbers the accounting readiness asks for (MER-4972). Distinct from sales_channel_id.", "type": "string", "example": "fiscal_machine", "nullable": true }, "issued_in_contingency": { "type": "boolean" }, "contingency_reason": { "type": "string", "nullable": true }, "contingency_note": { "type": "string", "nullable": true }, "contingency_reported_on": { "type": "string", "format": "date", "nullable": true }, "free_form_after_legal_date": { "description": "Nonblocking warning for a free-form invoice from the shared PA00093 legal date without contingency.", "type": "boolean" }, "unidentified_buyer_after_legal_date": { "description": "A non-blocking warning (ADR 0352, MER-5756): an invoice to the Consumidor final from 2027-04-19 (PA SNAT/2026/00093 art. 8.6) whose buyer lacks a name or a RIF, cédula or passport; drafts included, annulled-unnumbered excluded. Always present; not on the list.", "type": "boolean" }, "fiscal_machine_serial": { "description": "The serial of the fiscal machine that printed the invoice (ADR 0261, MER-4972), canonical: whitespace dropped, upper-cased, leading zeros kept. Stored apart from control_number and never copied into it. Null until captured.", "type": "string", "example": "Z1B-0042", "nullable": true }, "client_fiscal_snapshot": { "description": "Client fiscal identity frozen at approval (MER-2951). Null until the invoice is approved, or when the client had no fiscal identity to freeze.", "properties": { "document_type": { "type": "string", "nullable": true, "enum": [ "rif", "cedula", "passport" ] }, "document_number": { "type": "string", "nullable": true }, "legal_name": { "type": "string", "nullable": true }, "vat_taxpayer_type": { "type": "string", "nullable": true, "enum": [ "ordinary", "formal", "non_taxpayer" ] } }, "type": "object", "nullable": true }, "items": { "type": "array", "items": { "properties": { "id": { "type": "string" }, "category_id": { "type": "string" }, "item_id": { "type": "string" }, "quantity": { "type": "string", "example": "1.00" }, "unit_id": { "type": "string" }, "unit_price": { "type": "string", "example": "1000.00" }, "subtotal": { "type": "string", "example": "1000.00" }, "tax_id": { "type": "string" }, "tax_kind": { "type": "string", "example": "vat_general", "enum": [ "vat_general", "vat_reduced", "vat_additional", "exempt", "exonerated", "not_subject", "export", "other" ] }, "discount_percentage": { "type": "string", "example": "0.00" }, "accounting_center_id": { "type": "string" }, "accounting_account_id": { "type": "string" }, "sales_order_item_id": { "description": "The sales order line this line invoices; null unless the invoice was created from a sales order.", "type": "string", "format": "uuid", "nullable": true }, "sales_quote_item_id": { "description": "The sales quote line this line was converted from (MER-3893); null unless the invoice was converted from a sales quote.", "type": "string", "format": "uuid", "nullable": true } }, "type": "object" } }, "tax_summaries": { "description": "Per-tax snapshots materialized on approve; empty until the invoice is approved.", "type": "array", "items": { "properties": { "tax_id": { "type": "string", "format": "uuid" }, "tax_kind": { "type": "string", "example": "vat_general", "enum": [ "vat_general", "vat_reduced", "vat_additional", "exempt", "exonerated", "not_subject", "export", "other" ] }, "tax_percentage": { "type": "string", "example": "16.00" }, "taxable_base": { "type": "string", "example": "1000.00" }, "tax_amount": { "type": "string", "example": "160.00" }, "functional_base": { "description": "Taxable base frozen in the functional currency (MER-2951).", "type": "string", "example": "1000.00" }, "functional_tax": { "description": "Tax frozen in the functional currency: the percentage of the functional base (ADR 0126).", "type": "string", "example": "160.00" }, "reporting_base": { "description": "Taxable base frozen in the reporting currency.", "type": "string", "example": "1000.00" }, "reporting_tax": { "description": "Tax frozen in the reporting currency.", "type": "string", "example": "160.00" } }, "type": "object" } }, "breakdown": { "description": "Cobrado · Retenido · Notas · Pendiente in the document currency (MER-3178, MER-3693): collected + withheld + credited + pending = total. Null for an invoice awaiting approval (to_be_approved), a cancelled invoice and an opening, whose collections before its opening date are not in the system.", "required": [ "currency", "collected", "withheld", "credited", "pending" ], "properties": { "currency": { "description": "The document currency.", "type": "string", "example": "VES", "enum": [ "USD", "VES" ] }, "collected": { "description": "Cobrado: what applied collections relieved.", "type": "string", "example": "1000.00" }, "withheld": { "description": "Retenido: what the standing received withholdings, reported or supported, relieved; equals withheld_amount. 0.00 without any.", "type": "string", "example": "120.00" }, "credited": { "description": "Notas: what the active applications of its credit notes relieved. Debit notes never count.", "type": "string", "example": "11.60" }, "pending": { "description": "Pendiente: equals balance.", "type": "string", "example": "28.40" } }, "type": "object", "nullable": true }, "is_credited": { "description": "«Acreditada», derived and never stored: an approved regular invoice settled to zero by credit notes alone, with nothing collected nor withheld. Open debit notes do not suppress it. False whenever breakdown is null.", "type": "boolean", "example": false }, "has_live_notes": { "description": "Whether any credit or debit note of the invoice is not cancelled, drafts included, whatever note permissions the caller holds: what blocks its cancellation.", "type": "boolean", "example": true }, "notes": { "description": "Every note of the invoice, cancelled ones included, by emission date then code; only the kinds the caller may view. [] when there are none or the caller may view neither kind.", "type": "array", "items": { "$ref": "#/components/schemas/SalesInvoiceNote" } } }, "type": "object" } } } }, "404": { "description": "Sales invoice not found, or an id that is not a UUID, which the router answers before the controller with a `message` body." }, "403": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Backoffice - Sales Invoices" ], "summary": "Update a sales invoice", "operationId": "319b0e5e5a0757978e072d7f72f53bec", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "code", "customer_id", "payment_term", "emission_date", "accounting_center_id", "items" ], "type": "object", "allOf": [ { "anyOf": [ { "required": [ "accounting_account_receivable_id" ], "properties": { "kind": { "type": "string", "enum": [ "regular" ] }, "items": { "type": "array", "items": { "required": [ "accounting_account_id" ], "type": "object" } } }, "type": "object" }, { "description": "An advance edit may omit kind; account requirements follow the stored immutable kind.", "properties": { "kind": { "type": "string", "enum": [ "advance" ] } }, "type": "object" } ] }, { "properties": { "code": { "type": "string" }, "kind": { "description": "Omitted means regular on create; immutable on edit.", "type": "string", "enum": [ "regular", "advance" ] }, "advance_collection_id": { "description": "Required for advance creation; prohibited for regular creation; immutable on edit.", "type": "string", "format": "uuid" }, "advance_invoice_id": { "description": "The advance invoice this regular invoice deducts (MER-4263, ADR 0295). Omitted keeps the deduction the invoice holds, null removes it, a UUID sets or replaces it; whatever is kept is checked again. Prohibited on an advance invoice.", "type": "string", "format": "uuid", "nullable": true }, "price_list_id": { "type": "string", "format": "uuid", "nullable": true }, "customer_id": { "type": "string" }, "payment_term": { "type": "string", "enum": [ "cash", "five_days", "seven_days", "fifteen_days", "thirty_days" ] }, "emission_date": { "type": "string", "format": "date" }, "accounting_center_id": { "type": "string" }, "accounting_account_receivable_id": { "type": "string" }, "location_id": { "type": "string", "nullable": true }, "reference": { "type": "string", "nullable": true }, "invoice_number": { "description": "The fiscal numbers printed on the paper this invoice represents. Kept as printed (ADR 0380): surrounding whitespace is trimmed, and case, inner spaces and leading zeros are kept, so ' 00-0001 2345 ' is stored as '00-0001 2345'. What remains must be 1 to 30 letters, digits, spaces, hyphens, ° or º. The control number is unique among the company's non-cancelled invoices and notes, compared without whitespace or case (º counts as O). On this endpoint the two numbers are stored as a unit: omitting both keeps the identity the invoice already holds, while a request carrying either key replaces both, so send both whenever you send one or the omitted number is cleared.", "type": "string", "example": "00-001234", "nullable": true, "maxLength": 60 }, "control_number": { "description": "The fiscal numbers printed on the paper this invoice represents. Kept as printed (ADR 0380): surrounding whitespace is trimmed, and case, inner spaces and leading zeros are kept, so ' 00-0001 2345 ' is stored as '00-0001 2345'. What remains must be 1 to 30 letters, digits, spaces, hyphens, ° or º. The control number is unique among the company's non-cancelled invoices and notes, compared without whitespace or case (º counts as O). On this endpoint the two numbers are stored as a unit: omitting both keeps the identity the invoice already holds, while a request carrying either key replaces both, so send both whenever you send one or the omitted number is cleared.", "type": "string", "example": "00-00012345", "nullable": true, "maxLength": 60 }, "observations": { "type": "string", "nullable": true }, "currency": { "description": "Document currency; omit to keep the one the invoice already carries.", "type": "string", "nullable": true, "enum": [ "USD", "VES" ] }, "items": { "type": "array", "items": { "required": [ "id", "item_id", "quantity", "unit_id", "unit_price", "tax_id", "tax_percentage", "discount_percentage", "accounting_center_id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "category_id": { "type": "string", "format": "uuid", "nullable": true }, "item_id": { "type": "string", "format": "uuid" }, "item_name": { "type": "string", "nullable": true, "maxLength": 255 }, "quantity": { "description": "Number or decimal string with at most four fractional digits, at least 0.01.", "oneOf": [ { "type": "number", "example": 1.235, "minimum": 0.01 }, { "type": "string", "pattern": "^(?:[1-9]\\d*(?:\\.\\d{1,4})?|0\\.(?:0[1-9]\\d{0,2}|[1-9]\\d{0,3}))$", "example": "1.2350" } ] }, "unit_id": { "type": "string", "format": "uuid" }, "unit_price": { "description": "Number or decimal string with at most two fractional digits.", "oneOf": [ { "type": "number", "example": 100, "minimum": 0 }, { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,2})?$", "example": "100.00" } ] }, "tax_id": { "type": "string", "format": "uuid" }, "tax_percentage": { "description": "Number or decimal string with at most two fractional digits, from 0 to 100.", "oneOf": [ { "type": "number", "example": 16, "maximum": 100, "minimum": 0 }, { "type": "string", "pattern": "^(?:0*(?:[0-9]|[1-9][0-9])(?:\\.[0-9]{1,2})?|0*100(?:\\.0{1,2})?)$", "example": "16.00" } ] }, "discount_percentage": { "description": "Number or decimal string with at most two fractional digits, from 0 to 100.", "oneOf": [ { "type": "number", "example": 0, "maximum": 100, "minimum": 0 }, { "type": "string", "pattern": "^(?:0*(?:[0-9]|[1-9][0-9])(?:\\.[0-9]{1,2})?|0*100(?:\\.0{1,2})?)$", "example": "0.00" } ] }, "accounting_center_id": { "type": "string", "format": "uuid" }, "accounting_account_id": { "type": "string", "format": "uuid" } }, "type": "object" }, "minItems": 1 }, "preview": { "description": "Optional scale-2 preview. String amounts only. Null skips the comparison.", "required": [ "subtotal", "discount", "taxes", "total", "tax_groups" ], "properties": { "subtotal": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,2})?$", "example": "9.88" }, "discount": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,2})?$", "example": "0.12" }, "taxes": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,2})?$", "example": "0.00" }, "total": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,2})?$", "example": "9.88" }, "advance_deduction": { "description": "The advance invoice base this invoice deducts (MER-4263); omitted means 0.00. tax_groups then state the net groups, a group the deduction empties included.", "type": "string", "pattern": "^\\d+(?:\\.\\d{1,2})?$", "example": "1000.00" }, "tax_groups": { "type": "array", "items": { "required": [ "tax_id", "tax_percentage", "base", "tax" ], "properties": { "tax_id": { "type": "string", "format": "uuid" }, "tax_percentage": { "type": "string", "pattern": "^(?:0*(?:[0-9]|[1-9][0-9])(?:\\.[0-9]{1,2})?|0*100(?:\\.0{1,2})?)$", "example": "0.00" }, "base": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,2})?$", "example": "9.88" }, "tax": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,2})?$", "example": "0.00" } }, "type": "object" } } }, "type": "object", "nullable": true } }, "type": "object" } ] } } } }, "responses": { "200": { "description": "Sales invoice updated successfully" }, "400": { "description": "Bad request" }, "403": { "description": "Forbidden, and nothing is saved: the caller does not belong to the company, lacks the endpoint's permission (error_code null), or changed a line's proposed price without backoffice.sales.price-lists.override (sale_price_override_not_allowed, with the refused lines).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesDocumentWrite403" } } } }, "404": { "description": "Sales invoice not found, or an id that is not a UUID, which the router answers before the controller with a `message` body." }, "409": { "description": "The invoice cannot be modified in its current status (sales_invoice_cannot_be_modified), an items.*.id is already used by a line of any other document (sales_invoice_item_id_conflict; names only the id sent), the control number already belongs to another non-cancelled invoice or note of this company, or the advance invoice it deducts was applied, credited or cancelled (advance_invoice_not_pending, with advance_invoice_id and advance_invoice_status)", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "detail": { "type": "string" }, "error_code": { "type": "string", "example": "sales_invoice_control_number_already_registered", "enum": [ "sales_invoice_cannot_be_modified", "sales_invoice_item_id_conflict", "sales_invoice_control_number_already_registered", "advance_invoice_not_pending" ] }, "existing_code": { "description": "The code of the document, invoice or note, that already holds the control number, or null when a concurrent commit leaves the failure path unable to name it.", "type": "string", "example": "INV00001", "nullable": true }, "existing_kind": { "description": "The kind of the document that already holds the control number: invoices and notes share one control series. Null exactly when existing_code is null.", "type": "string", "example": "regular", "nullable": true, "enum": [ "regular", "opening", "credit_note", "debit_note", "advance" ] }, "advance_invoice_id": { "description": "Only on advance_invoice_not_pending.", "type": "string", "format": "uuid" }, "advance_invoice_status": { "description": "Only on advance_invoice_not_pending.", "type": "string", "enum": [ "applied", "credited", "cancelled" ] } }, "type": "object" } } } }, "422": { "description": "Balance invoice refusals (MER-4263): advance_deduction_invalid with `reason` advance_invoice_not_found, advance_invoice_not_approved, advance_balance_differs_from_base or advance_covers_whole_invoice when the deduction would leave nothing to collect (errors.advance_invoice_id), customer_mismatch (errors.customer_id), currency_mismatch (errors.currency) or date_after_invoice (errors.emission_date); advance_deduction_exceeds_base when the group with the advance invoice tax holds less base than it (errors.advance_invoice_id, with tax_id, tax_percentage, group_base and deduction). Advance refusals: advance_invoice_collection_not_advance, advance_invoice_mismatch, advance_invoice_date_mismatch, advance_invoice_total_mismatch, advance_invoice_single_tax, advance_invoice_goods_not_supported, advance_invoice_withholding_agent_not_supported, advance_invoice_no_service, keyed by advance_collection_id, for an Advance whose purpose is no_service (422); advance_already_invoiced (409). Validation error, sales_invoice_preview_mismatch, sales_invoice_tax_selection_invalid, sales_invoice_total_exceeds_storage, sales_invoice_counterparty_not_invoiceable, unsupported_document_currency, or, only for a user without backoffice.sales.price-lists.override, sale_price_line_unit_not_of_item (field_errors on items.N.unit_id) / invalid_calendar_day (an emission_date the proposed prices cannot be resolved on)", "content": { "application/json": { "schema": { "oneOf": [ { "required": [ "message", "errors" ], "properties": { "message": { "type": "string" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" }, { "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "error": { "type": "string", "example": "sales_invoice_preview_mismatch" }, "error_code": { "type": "string", "example": "sales_invoice_counterparty_not_invoiceable", "nullable": true }, "detail": { "type": "string" }, "client_id": { "type": "string", "format": "uuid" }, "reason": { "type": "string", "enum": [ "not_found", "fiscal_identity_incomplete", "advance_invoice_not_found", "advance_invoice_not_approved", "customer_mismatch", "currency_mismatch", "date_after_invoice", "advance_balance_differs_from_base", "advance_covers_whole_invoice" ] }, "tax_id": { "description": "With advance_deduction_exceeds_base: the tax of the group the advance invoice is deducted from.", "type": "string", "format": "uuid" }, "tax_percentage": { "description": "With advance_deduction_exceeds_base.", "type": "string", "example": "16.00" }, "group_base": { "description": "With advance_deduction_exceeds_base: the group's base before the deduction; 0.00 when no line carries that tax.", "type": "string", "example": "800.00" }, "deduction": { "description": "With advance_deduction_exceeds_base: the advance invoice base.", "type": "string", "example": "1000.00" }, "missing": { "type": "array", "items": { "type": "string" } }, "tax_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "field_errors": { "description": "With sale_price_line_unit_not_of_item: the refused lines' unit fields, such as items.0.unit_id.", "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object", "anyOf": [ { "required": [ "error_code" ] }, { "required": [ "error" ] } ] } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/sales-invoices/item-defaults/{id}": { "get": { "tags": [ "Backoffice - Sales - SalesInvoices" ], "summary": "Read the item defaults needed to prepare a sales document line", "operationId": "getSalesInvoiceItemDefaults", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Only this sales document line defaults", "content": { "application/json": { "schema": { "required": [ "name", "category_id", "type", "accounting_account_id" ], "properties": { "sales_tax": { "description": "The active Item sales tax in this company; otherwise null.", "required": [ "id", "name", "rate", "kind" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "rate": { "type": "string" }, "kind": { "type": "string" } }, "type": "object", "nullable": true }, "default_unit_id": { "description": "The configured purchase or sale unit for this document kind; null keeps the existing base/only-unit fallback.", "type": "string", "format": "uuid", "nullable": true }, "name": { "type": "string" }, "category_id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "inventoried", "non-inventoried" ] }, "accounting_account_id": { "type": "string", "format": "uuid", "nullable": true } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Requires company membership and this sales document create or update permission" }, "404": { "description": "Item not found in this company" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/sales-invoices": { "get": { "tags": [ "Backoffice - Sales Invoices" ], "summary": "Search sales invoices", "description": "Unknown query keys are ignored, and each accepted request carrying one is logged by key name only (MER-3306). Do not rely on it: they will answer 422 in a later change.", "operationId": "a1716803393f115731aed43aaed8f575", "parameters": [ { "name": "contingency_unreported", "in": "query", "description": "Only approved digital contingencies with no PDF report date.", "schema": { "type": "string", "enum": [ "1" ] } }, { "name": "status[]", "in": "query", "description": "Nonempty list. Scalar compatibility is supported for status, customer_id, responsible_user_id and kind.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "to_be_approved", "to_be_collected", "partially_collected", "fully_collected", "cancelled", "with_customer_credit", "applied", "advance_pending", "credited" ] }, "minItems": 1 } }, { "name": "customer_id[]", "in": "query", "description": "Nonempty list. Scalar compatibility is supported for status, customer_id, responsible_user_id and kind.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1 } }, { "name": "responsible_user_id[]", "in": "query", "description": "Nonempty list. Scalar compatibility is supported for status, customer_id, responsible_user_id and kind.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string" }, "minItems": 1 } }, { "name": "kind[]", "in": "query", "description": "Nonempty list. Mutually exclusive with kinds[]. Scalar compatibility is supported for status, customer_id, responsible_user_id and kind.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "regular", "opening" ] }, "minItems": 1 } }, { "name": "label_ids[]", "in": "query", "description": "Nonempty list. Scalar compatibility is supported for status, customer_id, responsible_user_id and kind.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1 } }, { "name": "responsible_user_id", "in": "query", "schema": { "type": "string", "maxLength": 255 } }, { "name": "sales_channel_id", "in": "query", "description": "Filter by Canal id (MER-4184). Distinct from issuance_channel.", "schema": { "type": "string", "format": "uuid" } }, { "name": "kind", "in": "query", "description": "Scalar compatibility; mutually exclusive with kinds[].", "schema": { "type": "string", "enum": [ "regular", "opening" ] } }, { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "customer_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "description": "One status, of whatever kinds are listed: kinds[]=credit_note&status=with_customer_credit lists the credit notes that keep Customer Credit.", "schema": { "type": "string", "enum": [ "to_be_approved", "to_be_collected", "partially_collected", "fully_collected", "cancelled", "with_customer_credit", "applied", "advance_pending", "credited" ] } }, { "name": "kinds[]", "in": "query", "description": "The kinds to list (MER-3176). Omitted, only the invoices proper (regular and opening) are listed. A note kind needs its own view permission as well (backoffice.sales.credit-notes.view, backoffice.sales.debit-notes.view), otherwise 403. The collection form sends regular, opening and debit_note, the kinds a collection settles.", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "regular", "opening", "credit_note", "debit_note", "advance" ] }, "minItems": 1 } }, { "name": "search_query", "in": "query", "description": "Code, reference, invoice number or control number contains", "required": false, "schema": { "type": "string" } }, { "name": "code", "in": "query", "schema": { "type": "string" } }, { "name": "emission_date_from", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "emission_date_to", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "group_by", "in": "query", "description": "Optional status grouping before pagination: to_be_approved, to_be_collected, fully_collected, partially_collected, with_customer_credit, advance_pending, applied, credited, cancelled. Group rank always ascends before the requested/default sort and code/id ties. Omitted, existing ungrouped ordering and counts are unchanged.", "required": false, "schema": { "type": "string", "enum": [ "status" ] } }, { "name": "sort_by", "in": "query", "description": "The column to order by; code when omitted. Ties break by code, then id, in sort_order, so pages never repeat or skip a row (MER-3178): «Todas» sends sort_by=emission_date&sort_order=desc.", "schema": { "type": "string", "enum": [ "emission_date", "code", "total", "created_at" ] } }, { "name": "sort_order", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "List of sales invoices", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "required": [ "is_credited" ], "properties": { "price_list_id": { "type": "string", "format": "uuid", "nullable": true }, "responsible_user_id": { "type": "string", "nullable": true }, "responsible_user_name": { "type": "string", "nullable": true }, "sales_channel_id": { "description": "The Canal this Comercio invoice was sold through (MER-4184). Null for Backoffice documents. Distinct from issuance_channel.", "type": "string", "format": "uuid", "nullable": true }, "sales_channel_name": { "description": "The Canal name at read time.", "type": "string", "nullable": true }, "labels": { "type": "array", "items": { "required": [ "id", "name", "tone", "archived" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "tone": { "type": "string" }, "archived": { "type": "boolean" } }, "type": "object" } }, "kind": { "description": "A note row carries no invoice items, and hasAccountingConfigurationGaps is always false on it (MER-3336).", "type": "string", "example": "regular", "enum": [ "regular", "opening", "credit_note", "debit_note", "advance" ] }, "is_credited": { "description": "«Acreditada», derived and never stored: an approved regular invoice settled to zero by credit notes alone, with nothing collected. Open debit notes do not suppress it. False for notes, openings, drafts and cancelled invoices.", "type": "boolean", "example": false }, "origin_sales_invoice_id": { "description": "The invoice a note row affects (MER-3178); null on an invoice row.", "type": "string", "format": "uuid", "nullable": true }, "origin_code": { "description": "That invoice's code; null on an invoice row.", "type": "string", "example": "INV2600001", "nullable": true }, "invoice_number": { "description": "The invoice number printed on the paper the invoice represents (MER-2950), kept as printed: trimmed, with case, inner spaces and leading zeros kept (ADR 0380). Null until captured.", "type": "string", "example": "00-001234", "nullable": true }, "control_number": { "description": "The control number printed on that paper (MER-2950, ADR 0162). Null until captured; a fiscal machine prints none, so a fiscal_machine invoice is never asked for one (ADR 0261, MER-4972).", "type": "string", "example": "00-00012345", "nullable": true }, "issuance_channel": { "description": "The Issuance Channel the invoice was written under, snapshotted from the company fiscal profile on every create, edit and capture (MER-2950): for example fiscal_machine, free_form or digital_printer. Null when the company had no fiscal profile. It decides which printed numbers the accounting readiness asks for (MER-4972). Distinct from sales_channel_id.", "type": "string", "example": "fiscal_machine", "nullable": true }, "free_form_after_legal_date": { "description": "Nonblocking warning for a free-form invoice from the shared PA00093 legal date without contingency.", "type": "boolean" }, "fiscal_machine_serial": { "description": "The serial of the fiscal machine that printed the invoice (ADR 0261, MER-4972), canonical: whitespace dropped, upper-cased, leading zeros kept. Stored apart from control_number and never copied into it. Null until captured.", "type": "string", "example": "Z1B-0042", "nullable": true }, "currency": { "description": "The invoice's Document Currency. A collection may only collect invoices in the Company functional currency (MER-2955).", "type": "string", "example": "USD", "enum": [ "USD", "VES" ] }, "balance": { "description": "Open balance in the Document Currency: the stored balance, so a cancelled credit note row reads its full valuation, never Customer Credit.", "type": "string", "example": "100.00" }, "functional_balance": { "type": "string", "example": "100.00" }, "reporting_balance": { "type": "string", "example": "100.00" } }, "type": "object" } }, "meta": { "properties": { "total": { "type": "integer" }, "per_page": { "type": "integer" }, "current_page": { "type": "integer" }, "counts": { "description": "All stored status counts, excluding only the status filter.", "type": "object", "additionalProperties": { "type": "integer" } }, "label_counts": { "description": "Distinct visible invoices by active label ID, excluding only label_ids.", "type": "object", "additionalProperties": { "type": "integer" } } }, "type": "object" } }, "type": "object" } } } }, "403": { "description": "Unauthorized, also when a requested note kind's view permission is missing" }, "422": { "description": "Invalid query, grouping, bounds, list values, reversed dates or simultaneous kind and kinds (`errors`)" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Sales Invoices" ], "summary": "Create a new sales invoice", "operationId": "b9a7c49523a008f8abbd60add3f30d40", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "id", "customer_id", "payment_term", "emission_date", "accounting_center_id", "items" ], "type": "object", "allOf": [ { "anyOf": [ { "required": [ "accounting_account_receivable_id" ], "properties": { "kind": { "type": "string", "enum": [ "regular" ] }, "items": { "type": "array", "items": { "required": [ "accounting_account_id" ], "type": "object" } } }, "type": "object" }, { "required": [ "kind", "advance_collection_id" ], "properties": { "kind": { "type": "string", "enum": [ "advance" ] } }, "type": "object" } ] }, { "properties": { "id": { "description": "Client-supplied invoice identifier. Returned as sales_invoice_id and required for approve/GET.", "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000" }, "code": { "description": "Ignored on create; the server assigns the fiscal code.", "type": "string", "nullable": true, "maxLength": 255 }, "responsible_user_id": { "description": "A user who belongs to this company.", "type": "string", "nullable": true, "maxLength": 255 }, "kind": { "description": "Omitted means regular on create; immutable on edit.", "type": "string", "enum": [ "regular", "advance" ] }, "advance_collection_id": { "description": "Required for advance creation; prohibited for regular creation; immutable on edit.", "type": "string", "format": "uuid" }, "advance_invoice_id": { "description": "The approved advance invoice (kind advance, status advance_pending) of the same customer and currency, dated no later than this invoice, whose whole base this regular invoice deducts from its group with the same tax (MER-4263, ADR 0295). Prohibited when kind is advance. Omitted or null deducts nothing.", "type": "string", "format": "uuid", "nullable": true }, "sales_channel_id": { "description": "Prohibited on Backoffice create (MER-4184). Distinct from issuance_channel (fiscal issuance). Comercio writers will set Canal later.", "type": "string", "format": "uuid", "nullable": true }, "price_list_id": { "type": "string", "format": "uuid", "nullable": true }, "customer_id": { "type": "string", "format": "uuid" }, "sales_order_id": { "type": "string", "format": "uuid", "nullable": true }, "payment_term": { "type": "string", "enum": [ "cash", "five_days", "seven_days", "fifteen_days", "thirty_days" ] }, "emission_date": { "type": "string", "format": "date" }, "accounting_center_id": { "type": "string", "format": "uuid" }, "accounting_account_receivable_id": { "description": "Required for regular invoices; unused for advance invoices.", "type": "string", "format": "uuid" }, "location_id": { "description": "Not required on create; mandatory on approve unless sales_order_id is set.", "type": "string", "format": "uuid", "nullable": true }, "reference": { "type": "string", "nullable": true, "maxLength": 255 }, "invoice_number": { "description": "The fiscal numbers printed on the paper this invoice represents. Kept as printed (ADR 0380): surrounding whitespace is trimmed, and case, inner spaces and leading zeros are kept, so ' 00-0001 2345 ' is stored as '00-0001 2345'. What remains must be 1 to 30 letters, digits, spaces, hyphens, ° or º. The control number is unique among the company's non-cancelled invoices and notes, compared without whitespace or case (º counts as O).", "type": "string", "example": "00-001234", "nullable": true, "maxLength": 60 }, "control_number": { "description": "The fiscal numbers printed on the paper this invoice represents. Kept as printed (ADR 0380): surrounding whitespace is trimmed, and case, inner spaces and leading zeros are kept, so ' 00-0001 2345 ' is stored as '00-0001 2345'. What remains must be 1 to 30 letters, digits, spaces, hyphens, ° or º. The control number is unique among the company's non-cancelled invoices and notes, compared without whitespace or case (º counts as O).", "type": "string", "example": "00-00012345", "nullable": true, "maxLength": 60 }, "observations": { "type": "string", "nullable": true }, "currency": { "description": "Document currency; defaults to the company functional currency.", "type": "string", "nullable": true, "enum": [ "USD", "VES" ] }, "items": { "type": "array", "items": { "required": [ "item_id", "quantity", "unit_id", "unit_price", "tax_id", "tax_percentage", "discount_percentage", "accounting_center_id" ], "properties": { "id": { "description": "Optional client line id; when omitted the server generates one.", "type": "string", "format": "uuid" }, "category_id": { "type": "string", "format": "uuid", "nullable": true }, "item_id": { "type": "string", "format": "uuid" }, "item_name": { "type": "string", "nullable": true, "maxLength": 255 }, "quantity": { "description": "Number or decimal string with at most four fractional digits, at least 0.01.", "oneOf": [ { "type": "number", "example": 1.235, "minimum": 0.01 }, { "type": "string", "pattern": "^(?:[1-9]\\d*(?:\\.\\d{1,4})?|0\\.(?:0[1-9]\\d{0,2}|[1-9]\\d{0,3}))$", "example": "1.2350" } ] }, "unit_id": { "type": "string", "format": "uuid" }, "unit_price": { "description": "Number or decimal string with at most two fractional digits.", "oneOf": [ { "type": "number", "example": 100, "minimum": 0 }, { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,2})?$", "example": "100.00" } ] }, "tax_id": { "type": "string", "format": "uuid" }, "tax_percentage": { "description": "Number or decimal string with at most two fractional digits, from 0 to 100.", "oneOf": [ { "type": "number", "example": 16, "maximum": 100, "minimum": 0 }, { "type": "string", "pattern": "^(?:0*(?:[0-9]|[1-9][0-9])(?:\\.[0-9]{1,2})?|0*100(?:\\.0{1,2})?)$", "example": "16.00" } ] }, "discount_percentage": { "description": "Number or decimal string with at most two fractional digits, from 0 to 100.", "oneOf": [ { "type": "number", "example": 0, "maximum": 100, "minimum": 0 }, { "type": "string", "pattern": "^(?:0*(?:[0-9]|[1-9][0-9])(?:\\.[0-9]{1,2})?|0*100(?:\\.0{1,2})?)$", "example": "0.00" } ] }, "accounting_center_id": { "type": "string", "format": "uuid" }, "accounting_account_id": { "type": "string", "format": "uuid" } }, "type": "object" }, "minItems": 1 }, "preview": { "description": "Optional scale-2 preview. String amounts only. Null skips the comparison.", "required": [ "subtotal", "discount", "taxes", "total", "tax_groups" ], "properties": { "subtotal": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,2})?$", "example": "9.88" }, "discount": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,2})?$", "example": "0.12" }, "taxes": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,2})?$", "example": "0.00" }, "total": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,2})?$", "example": "9.88" }, "advance_deduction": { "description": "The advance invoice base this invoice deducts (MER-4263); omitted means 0.00. tax_groups then state the net groups, a group the deduction empties included.", "type": "string", "pattern": "^\\d+(?:\\.\\d{1,2})?$", "example": "1000.00" }, "tax_groups": { "type": "array", "items": { "required": [ "tax_id", "tax_percentage", "base", "tax" ], "properties": { "tax_id": { "type": "string", "format": "uuid" }, "tax_percentage": { "type": "string", "pattern": "^(?:0*(?:[0-9]|[1-9][0-9])(?:\\.[0-9]{1,2})?|0*100(?:\\.0{1,2})?)$", "example": "0.00" }, "base": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,2})?$", "example": "9.88" }, "tax": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,2})?$", "example": "0.00" } }, "type": "object" } } }, "type": "object", "nullable": true } }, "type": "object" } ] } } } }, "responses": { "201": { "description": "Sales invoice created successfully. sales_invoice_id equals the client-supplied id.", "content": { "application/json": { "schema": { "required": [ "sales_invoice_id" ], "properties": { "sales_invoice_id": { "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000" } }, "type": "object" } } } }, "403": { "description": "Forbidden, and nothing is saved: the caller does not belong to the company, lacks the endpoint's permission (error_code null), or changed a line's proposed price without backoffice.sales.price-lists.override (sale_price_override_not_allowed, with the refused lines).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesDocumentWrite403" } } } }, "409": { "description": "A sales invoice with the supplied id already exists, an items.*.id is already used by a line of any document (sales_invoice_item_id_conflict; names only the id sent), the control number already belongs to another non-cancelled invoice or note of this company, sales_channel_inactive, advance_already_invoiced when the source advance is already reserved, or advance_invoice_not_pending when the advance invoice to deduct was applied, credited or cancelled (with advance_invoice_id and advance_invoice_status)", "content": { "application/json": { "schema": { "required": [ "title", "status", "detail", "error_code" ], "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "detail": { "type": "string", "example": "La factura de venta <123e4567-e89b-12d3-a456-426614174000> ya existe." }, "error_code": { "type": "string", "example": "sales_invoice_already_exists", "enum": [ "sales_invoice_already_exists", "sales_invoice_item_id_conflict", "sales_invoice_control_number_already_registered", "sales_channel_inactive", "advance_already_invoiced", "advance_invoice_not_pending" ] }, "advance_invoice_id": { "description": "Only on advance_invoice_not_pending.", "type": "string", "format": "uuid" }, "advance_invoice_status": { "description": "Only on advance_invoice_not_pending.", "type": "string", "enum": [ "applied", "credited", "cancelled" ] }, "existing_code": { "description": "The code of the document, invoice or note, that already holds the control number, or null when a concurrent commit leaves the failure path unable to name it. Only present on sales_invoice_control_number_already_registered.", "type": "string", "example": "INV00001", "nullable": true }, "existing_kind": { "description": "The kind of the document that already holds the control number: invoices and notes share one control series. Null exactly when existing_code is null.", "type": "string", "example": "regular", "nullable": true, "enum": [ "regular", "opening", "credit_note", "debit_note", "advance" ] } }, "type": "object" } } } }, "422": { "description": "Balance invoice refusals (MER-4263): advance_deduction_invalid with `reason` advance_invoice_not_found, advance_invoice_not_approved, advance_balance_differs_from_base or advance_covers_whole_invoice when the deduction would leave nothing to collect (errors.advance_invoice_id), customer_mismatch (errors.customer_id), currency_mismatch (errors.currency) or date_after_invoice (errors.emission_date); advance_deduction_exceeds_base when the group with the advance invoice tax holds less base than it (errors.advance_invoice_id, with tax_id, tax_percentage, group_base and deduction). Advance refusals: advance_invoice_collection_not_advance, advance_invoice_mismatch, advance_invoice_date_mismatch, advance_invoice_total_mismatch, advance_invoice_single_tax, advance_invoice_goods_not_supported, advance_invoice_withholding_agent_not_supported, advance_invoice_no_service, keyed by advance_collection_id, for an Advance whose purpose is no_service (422); advance_already_invoiced (409). Validation error, sales_invoice_preview_mismatch, sales_invoice_tax_selection_invalid, sales_invoice_total_exceeds_storage, sales_invoice_counterparty_not_invoiceable, unsupported_document_currency, or, only for a user without backoffice.sales.price-lists.override, sale_price_line_unit_not_of_item (field_errors on items.N.unit_id) / invalid_calendar_day (an emission_date the proposed prices cannot be resolved on)", "content": { "application/json": { "schema": { "oneOf": [ { "required": [ "message", "errors" ], "properties": { "message": { "type": "string" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" }, { "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "error": { "type": "string", "example": "sales_invoice_preview_mismatch" }, "error_code": { "type": "string", "example": "sales_invoice_counterparty_not_invoiceable", "nullable": true }, "detail": { "type": "string" }, "client_id": { "type": "string", "format": "uuid" }, "reason": { "type": "string", "enum": [ "not_found", "fiscal_identity_incomplete", "advance_invoice_not_found", "advance_invoice_not_approved", "customer_mismatch", "currency_mismatch", "date_after_invoice", "advance_balance_differs_from_base", "advance_covers_whole_invoice" ] }, "tax_id": { "description": "With advance_deduction_exceeds_base: the tax of the group the advance invoice is deducted from.", "type": "string", "format": "uuid" }, "tax_percentage": { "description": "With advance_deduction_exceeds_base.", "type": "string", "example": "16.00" }, "group_base": { "description": "With advance_deduction_exceeds_base: the group's base before the deduction; 0.00 when no line carries that tax.", "type": "string", "example": "800.00" }, "deduction": { "description": "With advance_deduction_exceeds_base: the advance invoice base.", "type": "string", "example": "1000.00" }, "missing": { "type": "array", "items": { "type": "string" } }, "tax_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "field_errors": { "description": "With sale_price_line_unit_not_of_item: the refused lines' unit fields, such as items.0.unit_id.", "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object", "anyOf": [ { "required": [ "error_code" ] }, { "required": [ "error" ] } ] } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/sales-invoices/proposed-fiscal-numbers": { "get": { "tags": [ "Backoffice - Sales Invoices" ], "summary": "Propose the next control and invoice numbers", "description": "Suggests the fiscal numbers of the next sales invoice as last used + 1 within the company's Active Control Series (ADR 0162). Computed on every read and never reserved: two users can see the same proposal, and registering a taken control number answers 409. The last number is the one with the greatest all-digit suffix; when no suffix is all digits, the most recent number is shown and no proposal is made. Cancelled invoices are ignored. Without an Active Control Series every field is null.", "operationId": "9a313200e4830a3b0e40dd0983803ec8", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "kind", "in": "query", "schema": { "type": "string", "default": "regular", "enum": [ "regular", "advance" ] } } ], "responses": { "200": { "description": "The proposal; every key is always present", "content": { "application/json": { "schema": { "required": [ "active_control_series", "last_control_number", "proposed_control_number", "last_invoice_number", "proposed_invoice_number" ], "properties": { "active_control_series": { "description": "Null when the company has no Active Control Series.", "type": "string", "example": "00", "nullable": true }, "last_control_number": { "description": "The last control number registered in the series.", "type": "string", "example": "00-00012345", "nullable": true }, "proposed_control_number": { "description": "The last control number + 1, keeping its width; null when the last one has a non-numeric suffix or there is none.", "type": "string", "example": "00-00012346", "nullable": true }, "last_invoice_number": { "description": "The last invoice number registered by the company.", "type": "string", "example": "000041", "nullable": true }, "proposed_invoice_number": { "description": "The last invoice number + 1, keeping its width; null when it is not all digits or there is none.", "type": "string", "example": "000042", "nullable": true } }, "type": "object" } } } }, "403": { "description": "Missing backoffice.sales.sales-invoices.create", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Forbidden" }, "status": { "type": "integer", "example": 403 }, "detail": { "type": "string", "example": "You do not have permission to access this resource." } }, "type": "object" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Internal Server Error" }, "status": { "type": "integer", "example": 500 }, "detail": { "type": "string", "example": "An Unexpected Error Occurred" } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/sales-invoices/{id}/responsible": { "put": { "tags": [ "Backoffice - Sales Invoices" ], "summary": "Reassign the responsible user of a sales invoice", "operationId": "dd49adf51a142f98baf312e6ba1b1bd7", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "responsible_user_id" ], "properties": { "responsible_user_id": { "description": "Company user id that becomes the Sales Invoice Responsable; null clears it", "type": "string", "nullable": true, "maxLength": 255 } }, "type": "object" } } } }, "responses": { "200": { "description": "Responsible reassigned" }, "403": { "description": "Forbidden" }, "404": { "description": "Sales invoice not found, or an id that is not a UUID, which the router answers before the controller with a `message` body." }, "409": { "description": "Responsible cannot be reassigned in the current status", "content": { "application/json": { "schema": { "properties": { "error_code": { "type": "string", "example": "sales_invoice_responsible_cannot_be_reassigned" } }, "type": "object" } } } }, "422": { "description": "Validation error" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/sales-notes/item-defaults/{id}": { "get": { "tags": [ "Backoffice - Sales - Sales Notes" ], "summary": "Read the item defaults needed to prepare a sales document line", "operationId": "getSalesNoteItemDefaults", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Only this sales document line defaults", "content": { "application/json": { "schema": { "required": [ "name", "category_id", "type", "accounting_account_id" ], "properties": { "default_unit_id": { "description": "The configured purchase or sale unit for this document kind; null keeps the existing base/only-unit fallback.", "type": "string", "format": "uuid", "nullable": true }, "name": { "type": "string" }, "category_id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "inventoried", "non-inventoried" ] }, "accounting_account_id": { "type": "string", "format": "uuid", "nullable": true } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Requires company membership and this sales document create or update permission" }, "404": { "description": "Item not found in this company" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/sales-note-origins/{id}": { "get": { "tags": [ "Backoffice - Sales - Sales Notes" ], "summary": "The origin business facts needed to prepare a sales note", "operationId": "cffb04be104a960861ce0adf308bfcf9", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Origin identity, frozen rate and source lines; no invoice audit metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesNoteOrigin" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "A sales note create permission is required" }, "404": { "description": "Origin not found in this company" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/sales-orders/{id}/approve": { "post": { "tags": [ "Backoffice - Sales Orders" ], "summary": "Approve a sales order", "operationId": "3e9780b5c094b374ab8512e4628a8a5b", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "financial_fingerprint": { "description": "Optional SHA-256 of the current stored-versus-recalculated comparison. Required only when those amounts differ.", "type": "string", "pattern": "^[a-f0-9]{64}$", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Sales order approved successfully", "content": { "application/json": { "schema": { "type": "object" } } } }, "409": { "description": "Order status does not allow approval, or Disponible does not cover every line while reserving on approval is switched on (insufficient_stock)", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/SalesOrderProblem" }, { "$ref": "#/components/schemas/InsufficientStockProblem" } ] } } } }, "403": { "description": "Unauthorized" }, "404": { "description": "Sales order not found" }, "422": { "description": "Stored amounts require acceptance, the supplied fingerprint is stale, or approval is blocked by an inventory dispatch precondition", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/SalesOrderProblem" }, { "$ref": "#/components/schemas/SalesOrderNativeValidation" }, { "required": [ "error", "detail", "financial_fingerprint", "previous", "proposed" ], "properties": { "error": { "type": "string", "example": "sales_order_historical_difference_acceptance_required", "enum": [ "sales_order_historical_difference_acceptance_required", "sales_order_historical_difference_acceptance_stale" ] }, "detail": { "type": "string" }, "financial_fingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "previous": { "type": "object" }, "proposed": { "type": "object" } }, "type": "object" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/sales-orders/{id}/cancel": { "post": { "tags": [ "Backoffice - Sales Orders" ], "summary": "Cancel a sales order", "operationId": "44c15f8d05a58d405a03479da6e01b8c", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Sales order cancelled successfully", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "Unauthorized" }, "404": { "description": "Sales order not found" }, "409": { "description": "Order status does not allow cancellation, or its dispatch already released stock (sales_order_cannot_be_modified / sales_order_has_warehouse_exit)", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "detail": { "type": "string", "example": "La orden de venta SOR2600007 tiene una salida de almacén (despacho ID2600034). Para cancelarla, primero cambia ese despacho a Pendiente." }, "error_code": { "type": "string", "example": "sales_order_has_warehouse_exit" }, "errors": { "type": "object", "nullable": true } }, "type": "object" } } } }, "422": { "description": "Request validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesOrderValidationResponse" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/sales-orders/{id}": { "get": { "tags": [ "Backoffice - Sales Orders" ], "summary": "Get a sales order by ID", "operationId": "d4d6bd64fc58bf1ca39e766b54de2ce4", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Sales order found", "content": { "application/json": { "schema": { "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "price_list_id": { "type": "string", "format": "uuid", "nullable": true }, "customer_id": { "type": "string", "format": "uuid" }, "customer_name": { "type": "string", "nullable": true }, "sales_quote_id": { "description": "The sales quote the order was converted from (MER-3892); null for an order created directly.", "type": "string", "format": "uuid", "nullable": true }, "sales_quote_code": { "description": "That quote's code; null for an order created directly.", "type": "string", "example": "COT2600001", "nullable": true }, "responsible_user_id": { "type": "string", "nullable": true }, "responsible_user_name": { "type": "string", "nullable": true }, "labels": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "tone": { "type": "string" }, "archived": { "type": "boolean" } }, "type": "object" } }, "payment_term": { "type": "string", "enum": [ "cash", "five_days", "seven_days", "fifteen_days", "thirty_days" ] }, "emission_date": { "type": "string", "format": "date" }, "accounting_center_id": { "type": "string", "format": "uuid" }, "accounting_account_receivable_id": { "type": "string", "format": "uuid" }, "receivable_account_name": { "type": "string", "nullable": true }, "location_id": { "type": "string", "format": "uuid", "nullable": true }, "status": { "type": "string" }, "reference": { "type": "string", "nullable": true }, "subtotal": { "type": "string" }, "discount": { "type": "string" }, "taxes": { "type": "string" }, "total": { "type": "string" }, "balance": { "type": "string" }, "observations": { "type": "string", "nullable": true }, "company_id": { "type": "string", "format": "uuid" }, "sales_invoice_id": { "type": "string", "format": "uuid", "nullable": true }, "sales_invoice_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "sales_invoices": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "status": { "type": "string" }, "total": { "type": "string" }, "currency": { "type": "string", "enum": [ "USD", "VES" ] } }, "type": "object" } }, "dispatch": { "description": "Despacho de Inventario de la orden de venta. null cuando la orden no tiene despacho: aún sin aprobar o sin salida de almacén asociada.", "required": [ "id", "code", "status" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string", "example": "ID2600034" }, "status": { "type": "string", "example": "partial", "enum": [ "pending", "partial", "completed", "cancelled", "closed_short" ] } }, "type": "object", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "items": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "category_id": { "type": "string", "format": "uuid" }, "item_id": { "type": "string", "format": "uuid" }, "quantity": { "type": "string" }, "unit_id": { "type": "string", "format": "uuid" }, "unit_price": { "type": "string" }, "subtotal": { "type": "string" }, "tax_id": { "type": "string", "format": "uuid" }, "tax_percentage": { "type": "string" }, "discount_percentage": { "type": "string" }, "accounting_center_id": { "type": "string", "format": "uuid" }, "accounting_account_id": { "type": "string", "format": "uuid" }, "sales_quote_item_id": { "description": "The sales quote line this line was converted from (MER-3892); null on a line entered directly.", "type": "string", "format": "uuid", "nullable": true }, "remaining_quantity": { "description": "Ordered quantity minus invoiced quantity for this line across linked non-cancelled sales invoices (scale-4 decimal string).", "type": "string" } }, "type": "object" } } }, "type": "object" } } } }, "403": { "description": "Unauthorized" }, "404": { "description": "Sales order not found" }, "422": { "description": "Request validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesOrderValidationResponse" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Backoffice - Sales Orders" ], "summary": "Update a sales order", "operationId": "42b28cf8c750c7c87f2063d5df96b9ce", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "code", "customer_id", "payment_term", "emission_date", "accounting_center_id", "accounting_account_receivable_id", "items" ], "properties": { "code": { "type": "string", "maxLength": 255 }, "price_list_id": { "description": "Lista de precios; null usa el precio base. Cambiarla requiere permiso de precio propuesto.", "type": "string", "format": "uuid", "nullable": true }, "customer_id": { "type": "string", "format": "uuid" }, "payment_term": { "type": "string", "enum": [ "cash", "five_days", "seven_days", "fifteen_days", "thirty_days" ] }, "emission_date": { "type": "string", "format": "date" }, "accounting_center_id": { "type": "string", "format": "uuid" }, "accounting_account_receivable_id": { "type": "string", "format": "uuid" }, "location_id": { "type": "string", "format": "uuid", "nullable": true }, "reference": { "type": "string", "nullable": true, "maxLength": 255 }, "observations": { "type": "string", "nullable": true }, "items": { "type": "array", "items": { "required": [ "id", "category_id", "item_id", "quantity", "unit_id", "unit_price", "tax_id", "tax_percentage", "discount_percentage", "accounting_center_id", "accounting_account_id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "category_id": { "type": "string", "format": "uuid" }, "item_id": { "type": "string", "format": "uuid" }, "quantity": { "description": "Number or decimal string with at most four fractional digits, at least 0.01.", "oneOf": [ { "type": "number", "example": 1.5, "minimum": 0.01 }, { "type": "string", "pattern": "^(?:[1-9]\\d*(?:\\.\\d{1,4})?|0\\.(?:0[1-9]\\d{0,2}|[1-9]\\d{0,3}))$", "example": "1.5000" } ] }, "unit_id": { "type": "string", "format": "uuid" }, "unit_price": { "description": "Number or decimal string with at most two fractional digits.", "oneOf": [ { "type": "number", "example": 10, "minimum": 0 }, { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,2})?$", "example": "10.00" } ] }, "tax_id": { "type": "string", "format": "uuid" }, "tax_percentage": { "description": "Number or decimal string with at most two fractional digits, from 0 to 100.", "oneOf": [ { "type": "number", "example": 16, "maximum": 100, "minimum": 0 }, { "type": "string", "pattern": "^(?:0*(?:[0-9]|[1-9][0-9])(?:\\.[0-9]{1,2})?|0*100(?:\\.0{1,2})?)$", "example": "16.00" } ] }, "discount_percentage": { "description": "Number or decimal string with at most two fractional digits, from 0 to 100.", "oneOf": [ { "type": "number", "example": 10, "maximum": 100, "minimum": 0 }, { "type": "string", "pattern": "^(?:0*(?:[0-9]|[1-9][0-9])(?:\\.[0-9]{1,2})?|0*100(?:\\.0{1,2})?)$", "example": "10.00" } ] }, "accounting_center_id": { "type": "string", "format": "uuid" }, "accounting_account_id": { "type": "string", "format": "uuid" } }, "type": "object" }, "minItems": 1 }, "preview": { "description": "Optional scale-2 preview. String amounts only. Null skips the comparison.", "required": [ "subtotal", "discount", "taxes", "total", "tax_groups" ], "properties": { "subtotal": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,2})?$" }, "discount": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,2})?$" }, "taxes": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,2})?$" }, "total": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,2})?$" }, "tax_groups": { "type": "array", "items": { "required": [ "tax_id", "tax_percentage", "base", "tax" ], "properties": { "tax_id": { "type": "string", "format": "uuid" }, "tax_percentage": { "type": "string", "pattern": "^(?:0*(?:[0-9]|[1-9][0-9])(?:\\.[0-9]{1,2})?|0*100(?:\\.0{1,2})?)$" }, "base": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,2})?$" }, "tax": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,2})?$" } }, "type": "object" } } }, "type": "object", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Sales order updated successfully", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "Forbidden, and nothing is saved: the caller does not belong to the company, lacks the endpoint's permission (error_code null), or changed a line's proposed price without backoffice.sales.price-lists.override (sale_price_override_not_allowed, with the refused lines).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesDocumentWrite403" } } } }, "404": { "description": "Sales order not found" }, "409": { "description": "Order cannot be modified in current status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesOrderProblem" } } } }, "422": { "description": "Validation error, or sales_order_preview_mismatch / sales_order_tax_selection_invalid / invalid_calendar_day (an emission_date the proposed prices cannot be resolved on; only for a user without backoffice.sales.price-lists.override)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesOrderValidationResponse" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/sales-orders/{salesOrderId}/invoice": { "post": { "tags": [ "Sales Orders" ], "summary": "Crear factura de venta desde orden de venta", "operationId": "f0fcdad3c102e42c58f0cb030b91962b", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "salesOrderId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "emission_date" ], "properties": { "code": { "description": "Optional - will be auto-generated if not provided", "type": "string", "example": "Auto-generado" }, "emission_date": { "type": "string", "format": "date", "example": "2025-07-05" }, "items": { "description": "Optional partial invoice quantities by order line id. When omitted, remaining available quantity is invoiced.", "type": "array", "items": { "required": [ "id", "quantity" ], "properties": { "id": { "type": "string", "format": "uuid" }, "quantity": { "description": "Number or decimal string with at most four fractional digits, at least 0.01.", "oneOf": [ { "type": "number", "example": 0.5, "minimum": 0.01 }, { "type": "string", "pattern": "^(?:[1-9]\\d*(?:\\.\\d{1,4})?|0\\.(?:0[1-9]\\d{0,2}|[1-9]\\d{0,3}))$", "example": "0.5000" } ] } }, "type": "object" }, "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Factura de venta creada exitosamente desde orden de venta", "content": { "application/json": { "schema": { "properties": { "sales_invoice_id": { "type": "string", "format": "uuid" } }, "type": "object" } } } }, "401": { "description": "No autorizado" }, "403": { "description": "Sin permisos suficientes" }, "404": { "description": "Orden de venta no encontrada" }, "409": { "description": "La orden de venta no puede ser facturada o ya fue facturada" }, "422": { "description": "Error de validación (Problem JSON con errors) o sales_order_invoice_quantity_exceeds_remaining (cuerpo error, detail, line_id, requested, remaining)" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/sales-orders/item-defaults/{id}": { "get": { "tags": [ "Backoffice - Sales - SalesOrders" ], "summary": "Read the item defaults needed to prepare a sales document line", "operationId": "getSalesOrderItemDefaults", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Only this sales document line defaults", "content": { "application/json": { "schema": { "required": [ "name", "category_id", "type", "accounting_account_id", "average_cost" ], "properties": { "sales_tax": { "description": "The active Item sales tax in this company; otherwise null.", "required": [ "id", "name", "rate", "kind" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "rate": { "type": "string" }, "kind": { "type": "string" } }, "type": "object", "nullable": true }, "default_unit_id": { "description": "The configured purchase or sale unit for this document kind; null keeps the existing base/only-unit fallback.", "type": "string", "format": "uuid", "nullable": true }, "name": { "type": "string" }, "category_id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "inventoried", "non-inventoried" ] }, "accounting_account_id": { "type": "string", "format": "uuid", "nullable": true }, "average_cost": { "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Requires company membership and this sales document create or update permission" }, "404": { "description": "Item not found in this company" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/sales-orders": { "get": { "tags": [ "Backoffice - Sales Orders" ], "summary": "Search sales orders", "operationId": "f97a8f84624e12d32cad0523fecf11c8", "parameters": [ { "name": "status[]", "in": "query", "description": "Array filter; scalar compatibility supported except label_ids.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "pending_approval", "to_be_invoiced", "partially_invoiced", "fully_invoiced", "cancelled", "all" ] } } }, { "name": "customer_id[]", "in": "query", "description": "Array filter; scalar compatibility supported except label_ids.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" } } }, { "name": "responsible_user_id[]", "in": "query", "description": "Array filter; scalar compatibility supported except label_ids.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "location_id[]", "in": "query", "description": "Array filter; scalar compatibility supported except label_ids.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" } } }, { "name": "label_ids[]", "in": "query", "description": "Array filter; scalar compatibility supported except label_ids.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" } } }, { "name": "responsible_user_id", "in": "query", "schema": { "type": "string" } }, { "name": "location_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "sort_by", "in": "query", "schema": { "type": "string", "enum": [ "emission_date", "code", "total", "created_at" ] } }, { "name": "sort_order", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "group_by", "in": "query", "schema": { "type": "string", "enum": [ "status" ] } }, { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 15, "maximum": 100, "minimum": 1 } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "search_query", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "date_from", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "date_to", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "customer_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Sales orders found", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "price_list_id": { "type": "string", "format": "uuid", "nullable": true }, "customer_id": { "type": "string", "format": "uuid" }, "customer_name": { "type": "string", "nullable": true }, "responsible_user_id": { "type": "string", "nullable": true }, "responsible_user_name": { "type": "string", "nullable": true }, "labels": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "tone": { "type": "string" }, "archived": { "type": "boolean" } }, "type": "object" } }, "payment_term": { "type": "string", "enum": [ "cash", "five_days", "seven_days", "fifteen_days", "thirty_days" ] }, "emission_date": { "type": "string", "format": "date" }, "status": { "type": "string" }, "reference": { "type": "string", "nullable": true }, "total": { "type": "string" }, "balance": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" } }, "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "meta": { "properties": { "counts": { "description": "All five status counts, excluding only status.", "type": "object", "additionalProperties": { "type": "integer" } }, "label_counts": { "description": "Distinct orders by active label, excluding only label_ids.", "type": "object", "additionalProperties": { "type": "integer" } } }, "type": "object" } }, "type": "object" } } } }, "403": { "description": "Unauthorized" }, "422": { "description": "Request validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesOrderValidationResponse" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Sales Orders" ], "summary": "Create a new sales order", "operationId": "60f83f1b63db3f1671b5756a54ed5a37", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "id", "customer_id", "payment_term", "emission_date", "accounting_center_id", "accounting_account_receivable_id", "items" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000" }, "price_list_id": { "description": "Lista de precios; null usa el precio base. Cambiarla requiere permiso de precio propuesto.", "type": "string", "format": "uuid", "nullable": true }, "customer_id": { "type": "string", "format": "uuid" }, "responsible_user_id": { "description": "Initial Responsable; must be a company member", "type": "string", "nullable": true, "maxLength": 255 }, "payment_term": { "type": "string", "enum": [ "cash", "five_days", "seven_days", "fifteen_days", "thirty_days" ] }, "emission_date": { "type": "string", "format": "date" }, "accounting_center_id": { "type": "string", "format": "uuid" }, "accounting_account_receivable_id": { "type": "string", "format": "uuid" }, "location_id": { "type": "string", "format": "uuid", "nullable": true }, "reference": { "type": "string", "nullable": true, "maxLength": 255 }, "observations": { "type": "string", "nullable": true }, "items": { "type": "array", "items": { "required": [ "id", "category_id", "item_id", "quantity", "unit_id", "unit_price", "tax_id", "tax_percentage", "discount_percentage", "accounting_center_id", "accounting_account_id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "category_id": { "type": "string", "format": "uuid" }, "item_id": { "type": "string", "format": "uuid" }, "quantity": { "description": "Number or decimal string with at most four fractional digits, at least 0.01.", "oneOf": [ { "type": "number", "example": 1.5, "minimum": 0.01 }, { "type": "string", "pattern": "^(?:[1-9]\\d*(?:\\.\\d{1,4})?|0\\.(?:0[1-9]\\d{0,2}|[1-9]\\d{0,3}))$", "example": "1.5000" } ] }, "unit_id": { "type": "string", "format": "uuid" }, "unit_price": { "description": "Number or decimal string with at most two fractional digits.", "oneOf": [ { "type": "number", "example": 10, "minimum": 0 }, { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,2})?$", "example": "10.00" } ] }, "tax_id": { "type": "string", "format": "uuid" }, "tax_percentage": { "description": "Number or decimal string with at most two fractional digits, from 0 to 100.", "oneOf": [ { "type": "number", "example": 16, "maximum": 100, "minimum": 0 }, { "type": "string", "pattern": "^(?:0*(?:[0-9]|[1-9][0-9])(?:\\.[0-9]{1,2})?|0*100(?:\\.0{1,2})?)$", "example": "16.00" } ] }, "discount_percentage": { "description": "Number or decimal string with at most two fractional digits, from 0 to 100.", "oneOf": [ { "type": "number", "example": 10, "maximum": 100, "minimum": 0 }, { "type": "string", "pattern": "^(?:0*(?:[0-9]|[1-9][0-9])(?:\\.[0-9]{1,2})?|0*100(?:\\.0{1,2})?)$", "example": "10.00" } ] }, "accounting_center_id": { "type": "string", "format": "uuid" }, "accounting_account_id": { "type": "string", "format": "uuid" } }, "type": "object" }, "minItems": 1 }, "preview": { "description": "Optional scale-2 preview. String amounts only. Null skips the comparison.", "required": [ "subtotal", "discount", "taxes", "total", "tax_groups" ], "properties": { "subtotal": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,2})?$", "example": "15.00" }, "discount": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,2})?$", "example": "1.50" }, "taxes": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,2})?$", "example": "0.00" }, "total": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,2})?$", "example": "13.50" }, "tax_groups": { "type": "array", "items": { "required": [ "tax_id", "tax_percentage", "base", "tax" ], "properties": { "tax_id": { "type": "string", "format": "uuid" }, "tax_percentage": { "type": "string", "pattern": "^(?:0*(?:[0-9]|[1-9][0-9])(?:\\.[0-9]{1,2})?|0*100(?:\\.0{1,2})?)$", "example": "0.00" }, "base": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,2})?$", "example": "13.50" }, "tax": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,2})?$", "example": "0.00" } }, "type": "object" } } }, "type": "object", "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Sales order created successfully", "content": { "application/json": { "schema": { "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "status": { "type": "string" } }, "type": "object" } } } }, "403": { "description": "Forbidden, and nothing is saved: the caller does not belong to the company, lacks the endpoint's permission (error_code null), or changed a line's proposed price without backoffice.sales.price-lists.override (sale_price_override_not_allowed, with the refused lines).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesDocumentWrite403" } } } }, "422": { "description": "Validation error, or sales_order_preview_mismatch / sales_order_tax_selection_invalid / invalid_calendar_day (an emission_date the proposed prices cannot be resolved on; only for a user without backoffice.sales.price-lists.override)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesOrderValidationResponse" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/sales-orders/{id}/responsible": { "put": { "tags": [ "Backoffice - Sales Orders" ], "summary": "Reassign the responsible user of a sales order", "operationId": "be6245935160cd937887c6d10ce3ae0c", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "responsible_user_id" ], "properties": { "responsible_user_id": { "description": "Company user id that becomes the Sales Order Responsable; null clears it", "type": "string", "nullable": true, "maxLength": 255 } }, "type": "object" } } } }, "responses": { "200": { "description": "Responsible reassigned" }, "403": { "description": "Forbidden" }, "404": { "description": "Sales order not found, or an id that is not a UUID, which the router answers before the controller with a `message` body." }, "409": { "description": "Responsible cannot be reassigned in the current status", "content": { "application/json": { "schema": { "properties": { "error_code": { "type": "string", "example": "sales_order_responsible_cannot_be_reassigned" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesOrderValidationResponse" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/sales-quotes/{id}/convert": { "post": { "tags": [ "Backoffice - Sales Quotes" ], "summary": "Convert a sales quote into a sales order or a sales invoice", "description": "Converts a sent or accepted quote, still valid on the company's today, once: into a sales order awaiting approval (pending_approval, USD quotes only) or into a direct sales invoice awaiting approval (to_be_approved, in the quote's currency, USD or VES). The new document copies the quote's header and lines with their exact quantities, prices, discounts and taxes, links back to the quote by header (sales_quote_id) and by line (sales_quote_item_id), and reserves no stock: an order reserves on approval, and so does a direct invoice. An invoice's lines are checked against the tax catalog, which stamps each line's tax kind; it may name a location_id. A sent quote becomes accepted, with responded_at set; the quote records converted_document_type and converted_document_id. The response reports in price_changes the lines quoted at the server's proposal whose price moved since, resolved with the quote's list and currency on the new document's emission date; the new document keeps the quoted prices and the conversion is never refused for them (MER-3894). Requires backoffice.sales.sales-quotes.convert and the target's create permission (backoffice.sales.sales-orders.create for sales_order, backoffice.sales.sales-invoices.create for sales_invoice).", "operationId": "13025ee56bfc59958f3ccfd9692cbef1", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesQuoteConvertRequest" } } } }, "responses": { "201": { "description": "Sales quote converted: the document it became and the quoted prices that moved since", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesQuoteConversionResponse" } } } }, "403": { "description": "Missing backoffice.sales.sales-quotes.convert, or the target's create permission (backoffice.sales.sales-orders.create for sales_order, backoffice.sales.sales-invoices.create for sales_invoice); nothing is written", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesQuoteProblem" } } } }, "404": { "description": "sales_quote_not_found from the controller, or the middleware's message for an unknown company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesQuoteNotFound404" } } } }, "409": { "description": "sales_quote_already_converted (with quote_status, converted_document_type and converted_document_id: the quote already became that order or invoice, go to it), sales_quote_expired (with quote_status and valid_until: valid_until is before the company's today, or the quote expired), sales_quote_not_convertible (with quote_status: only a sent or accepted quote converts), sales_quote_invalid_transition, sales_quote_already_exists, sales_quote_code_conflict, sales_quote_item_id_already_taken, sales_invoice_already_exists or sales_invoice_control_number_already_registered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesQuoteProblem" } } } }, "422": { "description": "Request validation failed (errors.target for an unknown target, errors.customer_id, errors.emission_date, or errors.location_id for a location that is not the company's or one sent with sales_order), sales_order_currency_not_supported (a VES quote into an order: an order is USD only), sales_quote_customer_required (a prospect's quote: field_errors.customer_id names the document, «la orden» or «la factura»), sales_quote_customer_mismatch (a client's quote for another client: field_errors.customer_id), invalid_item_unit_combination (a quoted unit no longer valid for its item) or invalid_calendar_day, all as a Problem body. Converting into a sales invoice may also answer sales_invoice_tax_selection_invalid (a quoted tax inactivated since quoting: error, detail, tax_ids), sales_invoice_total_exceeds_storage (error, detail) or sales_invoice_counterparty_not_invoiceable (the company has an active fiscal profile and the client is unknown or misses fiscal fields: error_code, detail, client_id, reason, missing).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesQuoteConvertRefusal422" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/sales-quotes/{id}": { "get": { "tags": [ "Backoffice - Sales Quotes" ], "summary": "Show a sales quote", "description": "The quote with its lines, its client's name (null for a prospect) and its labels. Another company's quote is not found.", "operationId": "b0442f6158da8faafb100d9b643e8416", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Sales quote found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesQuote" } } } }, "403": { "description": "Missing backoffice.sales.sales-quotes.view", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesQuoteProblem" } } } }, "404": { "description": "sales_quote_not_found from the controller, or the middleware's message for an unknown company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesQuoteNotFound404" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Backoffice - Sales Quotes" ], "summary": "Rewrite a draft sales quote", "description": "Rewrites the whole draft and reprices its lines. A quote that is no longer a draft answers 409 sales_quote_not_editable with its quote_status. An edit that changes nothing answers 200 and records nothing. A line kept as stored, while the price list and currency are unchanged, keeps its price_fingerprint even if the list price moved since; changing the list or the currency checks every line again.", "operationId": "24af556416113a93f10d7855f8e8d1de", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesQuoteUpdateRequest" } } } }, "responses": { "200": { "description": "Sales quote rewritten", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesQuoteWriteResponse" } } } }, "403": { "description": "Forbidden, and nothing is saved: the caller does not belong to the company, lacks backoffice.sales.sales-quotes.update (error_code null), selected another price list without override (sale_price_list_selection_not_allowed), or changed a line's proposed price without backoffice.sales.price-lists.override (sale_price_override_not_allowed, with the refused lines). A line kept with its stored item, unit, quantity and price, while the quote keeps its price list and currency, is never checked again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesDocumentWrite403" } } } }, "404": { "description": "sales_quote_not_found from the controller, or the middleware's message for an unknown company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesQuoteNotFound404" } } } }, "409": { "description": "sales_quote_not_editable (with quote_status) or sales_quote_item_id_already_taken", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesQuoteProblem" } } } }, "422": { "description": "Request validation failed (an unknown price list answers errors.price_list_id), or a domain refusal naming its fields in field_errors: sales_quote_price_list_not_applicable (field_errors.price_list_id: the list is inactive), sale_price_line_unit_not_of_item (field_errors.items.N.unit_id), sales_quote_tax_selection_invalid, among others. Every 422 comes before the 403 of a changed price.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesQuoteRefusal422" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/sales-quotes/item-defaults/{id}": { "get": { "tags": [ "Backoffice - Sales - SalesQuotes" ], "summary": "Read the item defaults needed to prepare a sales document line", "operationId": "getSalesQuoteItemDefaults", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Only this sales document line defaults", "content": { "application/json": { "schema": { "required": [ "name", "category_id", "type", "accounting_account_id" ], "properties": { "sales_tax": { "description": "The active Item sales tax in this company; otherwise null.", "required": [ "id", "name", "rate", "kind" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "rate": { "type": "string" }, "kind": { "type": "string" } }, "type": "object", "nullable": true }, "default_unit_id": { "description": "The configured purchase or sale unit for this document kind; null keeps the existing base/only-unit fallback.", "type": "string", "format": "uuid", "nullable": true }, "name": { "type": "string" }, "category_id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "inventoried", "non-inventoried" ] }, "accounting_account_id": { "type": "string", "format": "uuid", "nullable": true } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Requires company membership and this sales document create or update permission" }, "404": { "description": "Item not found in this company" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/sales-quotes": { "get": { "tags": [ "Backoffice - Sales Quotes" ], "summary": "List sales quotes", "description": "A page of the company's quotes. meta.counts holds every status under the same filters but the status one.", "operationId": "018edd7ef57932227a6013f3edfdc633", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "status[]", "in": "query", "description": "Statuses to show; all shows every one. A scalar status is accepted.", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "draft", "sent", "accepted", "rejected", "expired", "all" ] } } }, { "name": "customer_id[]", "in": "query", "description": "Clients to show. A scalar id is accepted.", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" } } }, { "name": "date_from", "in": "query", "description": "First emission day, included.", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "date_to", "in": "query", "description": "Last emission day, included; not before date_from.", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "search_query", "in": "query", "description": "Matches the code, the reference or the prospect's name.", "required": false, "schema": { "type": "string" } }, { "name": "sort_by", "in": "query", "required": false, "schema": { "type": "string", "default": "code", "enum": [ "emission_date", "valid_until", "code", "total", "created_at" ] } }, { "name": "sort_order", "in": "query", "required": false, "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 15, "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "Sales quotes found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesQuoteList" } } } }, "403": { "description": "Missing backoffice.sales.sales-quotes.view", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesQuoteProblem" } } } }, "422": { "description": "Request validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesQuoteProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Sales Quotes" ], "summary": "Draft a sales quote", "description": "Drafts a Cotización de venta for a client or a prospect, in USD or VES. Its totals come from its lines, priced as a sales invoice prices them. Each line's price is resolved from the quote's price list or the item's Precio base, and its price_fingerprint is stored when the price sent is that proposal. It never reserves stock.", "operationId": "12eb43d23f7dfb44ac4aaae3e638d69f", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesQuoteCreateRequest" } } } }, "responses": { "201": { "description": "Sales quote drafted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesQuoteWriteResponse" } } } }, "403": { "description": "Forbidden, and nothing is saved: the caller does not belong to the company, lacks backoffice.sales.sales-quotes.create (error_code null), selected another price list without override (sale_price_list_selection_not_allowed), or changed a line's proposed price without backoffice.sales.price-lists.override (sale_price_override_not_allowed, with the refused lines).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesDocumentWrite403" } } } }, "409": { "description": "sales_quote_already_exists, sales_quote_item_id_already_taken or sales_quote_code_conflict (retryable)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesQuoteProblem" } } } }, "422": { "description": "Request validation failed (an unknown price list answers errors.price_list_id), or a domain refusal naming its fields in field_errors: sales_quote_price_list_not_applicable (field_errors.price_list_id: the list is inactive), sale_price_line_unit_not_of_item (field_errors.items.N.unit_id), sales_quote_tax_selection_invalid, among others. Every 422 comes before the 403 of a changed price.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesQuoteRefusal422" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/sales-quotes/{id}/reject": { "post": { "tags": [ "Backoffice - Sales Quotes" ], "summary": "Record that the client rejected a sent sales quote", "description": "Rejects a sent quote, with an optional reason, and sets responded_at. Only a sent quote is rejected; any other status answers 409 sales_quote_invalid_transition with quote_status and target_status, and a quote already rejected answers it with both equal to rejected. A rejected quote is terminal.", "operationId": "496123856ea26c126d21e8d745ddf722", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesQuoteRejectRequest" } } } }, "responses": { "200": { "description": "Sales quote rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesQuoteWriteResponse" } } } }, "403": { "description": "Missing backoffice.sales.sales-quotes.update", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesQuoteProblem" } } } }, "404": { "description": "sales_quote_not_found from the controller, or the middleware's message for an unknown company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesQuoteNotFound404" } } } }, "409": { "description": "sales_quote_invalid_transition (with quote_status and target_status)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesQuoteProblem" } } } }, "422": { "description": "Request validation failed (errors.reason), or sales_quote_rejection_reason_invalid naming reason in field_errors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesQuoteProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/sales-quotes/{id}/reopen": { "post": { "tags": [ "Backoffice - Sales Quotes" ], "summary": "Reopen a sent sales quote to draft", "description": "Returns a sent quote to draft, so it is edited again, and clears its sent_at. Only a sent quote is reopened; any other status answers 409 sales_quote_invalid_transition with quote_status and target_status, and a quote already a draft answers it with both equal to draft.", "operationId": "a3120cfb2a4532af94226520eddc8b77", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Sales quote reopened", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesQuoteWriteResponse" } } } }, "403": { "description": "Missing backoffice.sales.sales-quotes.update", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesQuoteProblem" } } } }, "404": { "description": "sales_quote_not_found from the controller, or the middleware's message for an unknown company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesQuoteNotFound404" } } } }, "409": { "description": "sales_quote_invalid_transition (with quote_status and target_status)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesQuoteProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/sales-quotes/{id}/send": { "post": { "tags": [ "Backoffice - Sales Quotes" ], "summary": "Send a draft sales quote", "description": "Marks a draft as sent: a status the user sets, with no PDF and no email. Only a draft is sent; any other status answers 409 sales_quote_invalid_transition with quote_status and target_status, and a quote already sent answers it with both equal to sent. A sent quote is no longer edited until it is reopened.", "operationId": "0e8f860fb0e1d07e35a98ee9f3dfe153", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Sales quote sent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesQuoteWriteResponse" } } } }, "403": { "description": "Missing backoffice.sales.sales-quotes.update", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesQuoteProblem" } } } }, "404": { "description": "sales_quote_not_found from the controller, or the middleware's message for an unknown company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesQuoteNotFound404" } } } }, "409": { "description": "sales_quote_invalid_transition (with quote_status and target_status)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesQuoteProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/salespersons/lookup": { "get": { "tags": [ "Backoffice - Sales - Salesperson Lookups" ], "summary": "Lookup company users for the assigned-salesperson picker (tenant membership only — no backoffice.users.view required)", "operationId": "54a331f9fa22666baac0a37b959a96a2", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 20 } } ], "responses": { "200": { "description": "Paginated list of company users — minimal projection for dropdowns", "content": { "application/json": { "schema": { "properties": { "items": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 7 }, "name": { "type": "string", "example": "Maria Lopez" } }, "type": "object" } }, "total": { "type": "integer" }, "per_page": { "type": "integer" }, "current_page": { "type": "integer" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Authenticated but not a member of this tenant" }, "404": { "description": "Tenant does not exist (indistinguishable from missing route)" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/web-orders/{id}/approve": { "post": { "tags": [ "Backoffice - Sales - Web Orders" ], "summary": "Approve a Pedido web", "description": "Approves a reported Pedido web (MER-5429, ADR 0335) in one transaction: one cash Sales Invoice of the frozen lines to the buyer's Client, approved, whose dispatch adopts the order's existing Reservas with Reservado unchanged, and one Collection of its whole total, at the frozen rate when the rail is in another currency, which the authenticated reviewer must be permitted to agree (backoffice.sales.collections.agree-settlement-rate). The book valuation of the cash event stays the official rule. Any refusal rolls everything back: the order stays payment_reported with its report, its Reservas and its deadline, and the key is not burned. Under the order lock, the same key and body replays 200, the same key with another body answers 409 idempotency_key_conflict, another key on an approved order answers 200 with the current record, and another key on a rejected order answers 409 web_order_already_decided. A lost response is recovered by resending the same key and body, or by reading the detail. Requires backoffice.sales.web-orders.review. Answers Cache-Control: private, no-store.", "operationId": "b7dc2f001aadb2aea64788b3a7b6c99c", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderApproveRequest" } } } }, "responses": { "200": { "description": "The decision, on the first time and on every replay", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderDecisionResponse" } } } }, "401": { "description": "Unauthenticated: the auth middleware answers before the controller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderMiddlewareMessage" } } } }, "403": { "description": "agreed_settlement_rate_permission_required: the rail is in another currency and the reviewer may not agree its rate. Without backoffice.sales.web-orders.review the same envelope answers with error_code null, and a tenant the caller does not belong to with no error_code at all.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderReviewProblem" } } } }, "404": { "description": "web_order_not_found: unknown or another company's; a malformed id matches no route (message only)", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/WebOrderReviewProblem" }, { "$ref": "#/components/schemas/WebOrderMiddlewareMessage" } ] } } } }, "409": { "description": "web_order_not_reviewable (with order_status); web_order_version_conflict (with current_version): a correction arrived; web_order_already_decided (with order_status); idempotency_key_conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderReviewProblem" } } } }, "422": { "description": "The body failed its rules (errors names each field); payment_discrepancy (with expected and observed); payment_rail_unavailable; payment_rail_changed; frozen_rate_unavailable; client_fiscal_identity_incomplete (with client_id and missing); web_order_document_date_in_the_future; web_order_receivable_account_missing; cash_event_date_in_the_future; a settlement refusal such as derived_debt_does_not_match_applied_amounts or derived_debt_exceeds_open_balance (with derived, open, applied and currency); sales_channel_inactive or sales_channel_not_found; a unit or inventory configuration error of the invoice or its dispatch; {error: sales_invoice_tax_selection_invalid, detail, tax_ids[]} when a frozen tax is no longer in the catalog (a tax re-rated or deactivated since the freeze keeps its frozen rate and approves); or {error: accounting_configuration_incomplete, missing[]} for a closed period, OFFICIAL_RATE_NOT_AVAILABLE, OFFICIAL_RATE_STALE, IGTF_SUBJECT_UNCLASSIFIED or a missing posting account", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/WebOrderReviewProblem" }, { "required": [ "error", "detail", "tax_ids" ], "properties": { "error": { "type": "string", "enum": [ "sales_invoice_tax_selection_invalid" ] }, "detail": { "type": "string" }, "tax_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } } }, "type": "object" }, { "required": [ "error", "missing" ], "properties": { "error": { "type": "string", "enum": [ "accounting_configuration_incomplete" ] }, "missing": { "type": "array", "items": { "type": "object" } } }, "type": "object" } ] } } } }, "500": { "description": "Unexpected, reported: a lost race the three attempts did not settle, even one a step wrapped in its own error; or reservations_not_adoptable, web_order_terms_corrupted, web_order_active_report_missing or web_order_invoice_total_drifted. Resend the same key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderReviewProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/web-orders/{id}/attention": { "post": { "tags": [ "Backoffice - Sales - Web Orders" ], "summary": "Note attention on a Pedido web", "description": "Notes a staff reason on a reported Pedido web, such as a paid discrepancy that approve refused (MER-5429, D10). It never changes status, version, stock or review_due_at. Takes no idempotency key: the same reason repeated changes nothing, and another reason replaces it. Requires backoffice.sales.web-orders.review. Answers Cache-Control: private, no-store.", "operationId": "5a10a80cd34f5d83175720a23a7436c0", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderAttentionRequest" } } } }, "responses": { "200": { "description": "The note", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderAttentionResponse" } } } }, "401": { "description": "Unauthenticated: the auth middleware answers before the controller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderMiddlewareMessage" } } } }, "403": { "description": "Without backoffice.sales.web-orders.review (error_code null), or a tenant the caller does not belong to (no error_code at all)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderReviewProblem" } } } }, "404": { "description": "web_order_not_found: unknown or another company's; a malformed id matches no route (message only)", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/WebOrderReviewProblem" }, { "$ref": "#/components/schemas/WebOrderMiddlewareMessage" } ] } } } }, "409": { "description": "web_order_already_decided (with order_status): the order has a decision; web_order_not_reviewable (with order_status): it has no report awaiting one", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderReviewProblem" } } } }, "422": { "description": "The reason failed its rules (errors names it)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderReviewProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/pos/web-orders/{id}/claim": { "post": { "tags": [ "Backoffice - Sales - Web Orders" ], "summary": "Take a Pedido web at the till", "description": "Takes an unpaid Pedido web at the till (MER-5431). The claimant is the session's user and the shift is the Caja's open Turno, locked; any such key in the body is ignored. Only claim metadata moves: its version, status, Reservas, frozen terms and deadline stay, so the buyer's next report still carries her version. A new claim_cycle_id is issued every time. Lock order: Turno, order, key. The same key, actor and body replays 200 with the same bytes; the same key with another body or actor answers 409 idempotency_key_conflict; a refused attempt burns no key. A replay after the Turno closed answers cash_shift_not_open. Requires backoffice.sales.web-orders.claim; a POS session token reaches it. Answers Cache-Control: private, no-store.", "operationId": "claimPosWebOrder", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderClaimRequest" } } } }, "responses": { "200": { "description": "The claim, on the first time and on every replay", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderQueueCommandResult" } } } }, "401": { "description": "Unauthenticated: the auth middleware answers before the controller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderMiddlewareMessage" } } } }, "403": { "description": "Without backoffice.sales.web-orders.claim, or a caller who does not belong to the company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderQueueProblem" } } } }, "404": { "description": "cash_register_not_found; web_order_not_found: unknown, or of another company or Location, the same answer for each; a malformed id matches no route (message only)", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/WebOrderQueueProblem" }, { "$ref": "#/components/schemas/WebOrderMiddlewareMessage" } ] } } } }, "409": { "description": "cash_shift_not_open (with cash_register_id); web_order_expired, web_order_not_claimable, web_order_already_claimed, web_order_version_conflict (each with order_status, current_version, expires_at and claim); idempotency_key_conflict; web_order_already_charged (with charged_sale): a till charged it, so this names its sale. A claim whose Turno closed is taken through take-over", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderQueueProblem" } } } }, "422": { "description": "The body failed its rules (errors names each field); or counter_sale_cash_register_not_selling (with reason)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderQueueProblem" } } } }, "500": { "description": "Unexpected, reported: a lost race the three attempts did not settle. Resend the same key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderQueueProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/web-orders/{id}": { "get": { "tags": [ "Backoffice - Sales - Web Orders" ], "summary": "Show a Pedido web", "description": "A Pedido web as a reviewer reads it (MER-5429): frozen terms, payment reports, attention, decision and the documents approval created, with what approving it would refuse shown first (client.missing, settlement). attention, decision and each documents.* are null until they exist. Requires backoffice.sales.web-orders.view. Answers Cache-Control: private, no-store. The payload holds no object key, storefront URL, phone digest, frozen JSON or evidence digest: the evidence URL is built from the route. buyer_contact reaches a holder of backoffice.sales.web-orders.review only: the number the buyer verified, on an order of any status, or null until she verifies again; null for a requester who holds only .view.", "operationId": "60c1dae979fad4a8ea4b254b18367cde", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The order", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderReviewDetail" } } } }, "401": { "description": "Unauthenticated: the auth middleware answers before the controller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderMiddlewareMessage" } } } }, "403": { "description": "Without backoffice.sales.web-orders.view (error_code null), or a tenant the caller does not belong to (no error_code at all)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderReviewProblem" } } } }, "404": { "description": "web_order_not_found: unknown or another company's; a malformed id matches no route (message only)", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/WebOrderReviewProblem" }, { "$ref": "#/components/schemas/WebOrderMiddlewareMessage" } ] } } } }, "500": { "description": "web_order_terms_corrupted: the frozen terms cannot be read; reported", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderReviewProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/web-orders/{id}/release-leftovers": { "post": { "tags": [ "Backoffice - Sales - Web Orders" ], "summary": "Release a Pedido web's leftover Reservas", "description": "Releases the open remainder an interrupted or legacy path left on an ended Pedido web (MER-5430): only its active Reservas no dispatch line claimed, under the reason its status names (expired, rejected or cancelled). It writes no order column, no version and no event, so a second expiry cannot happen. No body and no idempotency key: a repeat finds nothing open and answers 0. Requires backoffice.sales.web-orders.review. Answers Cache-Control: private, no-store.", "operationId": "c0d71452d5881604082678cf345344fa", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "How many Reservas let go, 0 on a repeat", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderLeftoversReleased" } } } }, "401": { "description": "Unauthenticated: the auth middleware answers before the controller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderMiddlewareMessage" } } } }, "403": { "description": "Without backoffice.sales.web-orders.review (error_code null), or a tenant the caller does not belong to (no error_code at all)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderReviewProblem" } } } }, "404": { "description": "web_order_not_found: unknown or another company's; a malformed id matches no route (message only)", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/WebOrderReviewProblem" }, { "$ref": "#/components/schemas/WebOrderMiddlewareMessage" } ] } } } }, "409": { "description": "web_order_leftovers_not_releasable (with order_status): the order is awaiting_payment, payment_reported or approved, so it still owns its stock, or charged_in_store, whose stock its sale owns", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderReviewProblem" } } } }, "500": { "description": "Unexpected, reported: a lost race the three attempts did not settle, or web_order_terms_corrupted. It rolled back, so it is safe to resend.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderReviewProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/web-orders/notices/{noticeId}": { "get": { "tags": [ "Backoffice - Sales - Web Orders" ], "summary": "Show a Pedido web notice", "description": "A Pedido web notice's safe detail (MER-5442): its status, every attempt and every manual resend. Requires backoffice.sales.web-orders.view-notices. Answers Cache-Control: private, no-store. The destination, body, variables, idempotency key, attempt token, provider id and frozen request never appear; provider_confirmed only says whether a provider returned an id.", "operationId": "showWebOrderNotice", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "noticeId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The notice", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderNoticeDetail" } } } }, "401": { "description": "Unauthenticated: the auth middleware answers before the controller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderMiddlewareMessage" } } } }, "403": { "description": "Without backoffice.sales.web-orders.view-notices (error_code null), or a tenant the caller does not belong to (no error_code at all)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderNoticeProblem" } } } }, "404": { "description": "web_order_notice_not_found: unknown or another company's; a malformed id matches no route (message only)", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/WebOrderNoticeProblem" }, { "$ref": "#/components/schemas/WebOrderMiddlewareMessage" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/web-orders/notices/{noticeId}/resend": { "post": { "tags": [ "Backoffice - Sales - Web Orders" ], "summary": "Resend a Pedido web notice", "description": "Requeues a Pedido web notice its provider provably never accepted (MER-5442, PRD MER-2933 R7): only dead_letter or blocked, with no attempt a provider may hold. It opens a new generation with a fresh attempt budget and keeps every prior attempt; it rechecks the buyer at once, so a withdrawn consent or a changed destination answers the notice skipped instead. Nothing is sent by this call: the minute drain sends it. No recipient, body or URL can be given. The same key, actor and body replays 200 with the same bytes; the same key with another body or actor answers 409 idempotency_key_conflict; a refused attempt burns no key. Requires backoffice.sales.web-orders.resend-notices. Answers Cache-Control: private, no-store.", "operationId": "resendWebOrderNotice", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "noticeId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderNoticeResendRequest" } } } }, "responses": { "200": { "description": "The notice, pending in its new generation or skipped by the recheck, on the first time and on every replay", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderNoticeRow" } } } }, "401": { "description": "Unauthenticated: the auth middleware answers before the controller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderMiddlewareMessage" } } } }, "403": { "description": "Without backoffice.sales.web-orders.resend-notices (error_code null), or a tenant the caller does not belong to (no error_code at all)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderNoticeProblem" } } } }, "404": { "description": "web_order_notice_not_found: unknown or another company's; a malformed id matches no route (message only)", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/WebOrderNoticeProblem" }, { "$ref": "#/components/schemas/WebOrderMiddlewareMessage" } ] } } } }, "409": { "description": "web_order_notice_not_resendable (with notice_status): any status but dead_letter or blocked, or an attempt a provider may hold; web_order_notice_version_conflict (with current_attempt_count); idempotency_key_conflict; web_order_notice_requeue_limit_reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderNoticeProblem" } } } }, "422": { "description": "The body failed its rules (errors names each field)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderNoticeProblem" } } } }, "500": { "description": "Unexpected, reported: a lost race the three attempts did not settle. Resend the same key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderNoticeProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/web-orders/notices": { "get": { "tags": [ "Backoffice - Sales - Web Orders" ], "summary": "List Pedido web notices", "description": "The buyer notices of the company's Pedidos web (MER-5442): one page, newest change first, ties by id. Filter status=dead_letter or status=unknown for the ones waiting on staff. Blank values are absent. Requires backoffice.sales.web-orders.view-notices. Answers Cache-Control: private, no-store. No destination, body, variable, key, token or provider id ever appears.", "operationId": "listWebOrderNotices", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending", "sending", "accepted", "delivered", "undelivered", "unknown", "blocked", "dead_letter", "skipped" ] } }, { "name": "channel", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "whatsapp", "email" ] } }, { "name": "kind", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "reserved", "expiry_reminder", "expired", "approved", "rejected" ] } }, { "name": "web_order_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 25, "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "The page", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderNoticePage" } } } }, "401": { "description": "Unauthenticated: the auth middleware answers before the controller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderMiddlewareMessage" } } } }, "403": { "description": "Without backoffice.sales.web-orders.view-notices (error_code null), or a tenant the caller does not belong to (no error_code at all)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderNoticeProblem" } } } }, "422": { "description": "A parameter is invalid (errors names it)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderNoticeProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/web-orders/{id}/payment-reports/{reportId}/evidence": { "get": { "tags": [ "Backoffice - Sales - Web Orders" ], "summary": "Read a payment report's evidence", "description": "The private bytes of a payment report (MER-5429, D12), read through this authenticated route and never through a public URL. Requires backoffice.sales.web-orders.view. Answers X-Content-Type-Options: nosniff and Cache-Control: private, no-store.", "operationId": "e0b10a805950a737f3a8d794ceee0e8d", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "reportId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The image", "content": { "image/*": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Unauthenticated: the auth middleware answers before the controller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderMiddlewareMessage" } } } }, "403": { "description": "Without backoffice.sales.web-orders.view (error_code null), or a tenant the caller does not belong to (no error_code at all)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderReviewProblem" } } } }, "404": { "description": "web_order_not_found: an unknown order or report, a report of another order, or another company's", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/WebOrderReviewProblem" }, { "$ref": "#/components/schemas/WebOrderMiddlewareMessage" } ] } } } }, "503": { "description": "payment_evidence_unavailable: private storage failed or the stored bytes do not match their digest; reported", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderReviewProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/pos/web-orders": { "get": { "tags": [ "Backoffice - Sales - Web Orders" ], "summary": "List a Caja's Pedido web inbox", "description": "The Caja's Pedido web inbox (MER-5431): one page of the orders at the Location its Canal sells from, unpaid and within their deadline or with a reported payment, by expires_at then id, so a reported order keeps its original deadline and may sort first. A reported row is read-only here, and its review_url leads to the Backoffice, which refuses anyone without backoffice.sales.web-orders.view. An order overdue but not yet swept, and every ended order, is absent. No rows is an empty page; only the Caja answers 404. Blank query values count as absent. Requires backoffice.sales.web-orders.view-queue; a POS session token reaches it. Answers Cache-Control: private, no-store. Of the buyer only a name appears.", "operationId": "searchPosWebOrders", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "cash_register_id", "in": "query", "description": "The Caja whose Location to read.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1, "maximum": 1000, "minimum": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "maximum": 50, "minimum": 1 } } ], "responses": { "200": { "description": "The page", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderQueuePage" } } } }, "401": { "description": "Unauthenticated: the auth middleware answers before the controller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderMiddlewareMessage" } } } }, "403": { "description": "Without backoffice.sales.web-orders.view-queue, or a caller who does not belong to the company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderQueueProblem" } } } }, "404": { "description": "cash_register_not_found: unknown or another company's Caja", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderQueueProblem" } } } }, "422": { "description": "A parameter is invalid (errors names it); or counter_sale_cash_register_not_selling (with reason): a Caja that cannot sell never reads as an empty inbox", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderQueueProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/pos/web-orders/{id}": { "get": { "tags": [ "Backoffice - Sales - Web Orders" ], "summary": "Read a Pedido web at the till", "description": "One Pedido web at the Location of the Caja (MER-5431), in any status, since the till reads an order that ended under it: the inbox row's fields plus created_at and its public terms. An ended order answers claim null. Requires backoffice.sales.web-orders.view-queue; a POS session token reaches it. Answers Cache-Control: private, no-store.", "operationId": "findPosWebOrder", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "cash_register_id", "in": "query", "description": "The Caja whose Location to read.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The order", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderQueueDetail" } } } }, "401": { "description": "Unauthenticated: the auth middleware answers before the controller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderMiddlewareMessage" } } } }, "403": { "description": "Without backoffice.sales.web-orders.view-queue, or a caller who does not belong to the company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderQueueProblem" } } } }, "404": { "description": "cash_register_not_found; web_order_not_found: unknown, or of another company or Location, the same answer for each; a malformed id matches no route (message only)", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/WebOrderQueueProblem" }, { "$ref": "#/components/schemas/WebOrderMiddlewareMessage" } ] } } } }, "422": { "description": "cash_register_id is missing or not a UUID (errors names it); or counter_sale_cash_register_not_selling (with reason)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderQueueProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/web-orders/{id}/reject": { "post": { "tags": [ "Backoffice - Sales - Web Orders" ], "summary": "Reject a Pedido web", "description": "Rejects a reported Pedido web when no money arrived (MER-5429, D10): its Reservas release with reason rejected and the buyer may reserve again. A rejected order never reopens. Under the order lock, the same key and body replays 200, the same key with another body answers 409 idempotency_key_conflict, another key on a rejected order answers 200 with the current record, and another key on an approved order answers 409 web_order_already_decided. A failed attempt does not burn the key. Requires backoffice.sales.web-orders.review. Answers Cache-Control: private, no-store.", "operationId": "d1512986a747cbc1e0061a0cbe056bcb", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderRejectRequest" } } } }, "responses": { "200": { "description": "The decision, on the first time and on every replay", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderDecisionResponse" } } } }, "401": { "description": "Unauthenticated: the auth middleware answers before the controller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderMiddlewareMessage" } } } }, "403": { "description": "Without backoffice.sales.web-orders.review (error_code null), or a tenant the caller does not belong to (no error_code at all)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderReviewProblem" } } } }, "404": { "description": "web_order_not_found: unknown or another company's; a malformed id matches no route (message only)", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/WebOrderReviewProblem" }, { "$ref": "#/components/schemas/WebOrderMiddlewareMessage" } ] } } } }, "409": { "description": "web_order_not_reviewable (with order_status); web_order_version_conflict (with current_version): a correction arrived; web_order_already_decided (with order_status); idempotency_key_conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderReviewProblem" } } } }, "422": { "description": "The body failed its rules (errors names each field, no_money_received included)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderReviewProblem" } } } }, "500": { "description": "Unexpected, reported: a lost race the three attempts did not settle, or web_order_terms_corrupted. Resend the same key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderReviewProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/pos/web-orders/{id}/release": { "post": { "tags": [ "Backoffice - Sales - Web Orders" ], "summary": "Release an unpaid Pedido web", "description": "Lets an unpaid Pedido web go from the till (MER-5431): it ends cancelled, its version moves, any claim clears, its Reservas release with reason cancelled, and the buyer may reserve again. A reported payment refuses it: the review decides that money. The actor and reason never reach the buyer. claim_cycle_id must be sent: null says the till saw it unclaimed, so a claim it did not see refuses like a stale one. The same key, actor and body replays 200 with the same bytes and no second release; the same key with another body or actor answers 409 idempotency_key_conflict; a refused attempt burns no key. Requires backoffice.sales.web-orders.release; a POS session token reaches it. Answers Cache-Control: private, no-store.", "operationId": "releasePosWebOrder", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderReleaseRequest" } } } }, "responses": { "200": { "description": "The cancelled order with claim null, on the first time and on every replay", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderQueueCommandResult" } } } }, "401": { "description": "Unauthenticated: the auth middleware answers before the controller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderMiddlewareMessage" } } } }, "403": { "description": "Without backoffice.sales.web-orders.release, or a caller who does not belong to the company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderQueueProblem" } } } }, "404": { "description": "cash_register_not_found; web_order_not_found: unknown, or of another company or Location, the same answer for each; a malformed id matches no route (message only)", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/WebOrderQueueProblem" }, { "$ref": "#/components/schemas/WebOrderMiddlewareMessage" } ] } } } }, "409": { "description": "web_order_expired, web_order_not_releasable: no longer unpaid, a reported payment included; web_order_version_conflict; web_order_claim_conflict: not the cycle the till saw (each with order_status, current_version, expires_at and claim); idempotency_key_conflict; web_order_already_charged (with charged_sale): a till charged it, so this names its sale", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderQueueProblem" } } } }, "422": { "description": "The body failed its rules (errors names each field); or counter_sale_cash_register_not_selling (with reason)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderQueueProblem" } } } }, "500": { "description": "Unexpected, reported: a lost race the three attempts did not settle, or web_order_terms_corrupted. Resend the same key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderQueueProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/web-orders/reservation-leftovers": { "get": { "tags": [ "Backoffice - Sales - Web Orders" ], "summary": "List Pedidos web with leftover or overdue Reservas", "description": "What an operator can recover (MER-5430): kind leftover is an expired, rejected or cancelled Pedido web still holding at least one active Reserva no dispatch line claimed, which POST .../{id}/release-leftovers lets go of. Kind overdue is an order awaiting payment past its deadline, which the expiry job will expire and that route refuses. A fixed limit of 100 rows per kind, not pages: has_more says to work through them and read again. An empty list is 200. Requires backoffice.sales.web-orders.review. Answers Cache-Control: private, no-store. No client, buyer, reference or frozen terms.", "operationId": "dfd9c2d0a7aeeff1d9eecd7d46ebfa41", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderLeftoversList" } } } }, "401": { "description": "Unauthenticated: the auth middleware answers before the controller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderMiddlewareMessage" } } } }, "403": { "description": "Without backoffice.sales.web-orders.review (error_code null), or a tenant the caller does not belong to (no error_code at all)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderReviewProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/pos/web-orders/{id}/return": { "post": { "tags": [ "Backoffice - Sales - Web Orders" ], "summary": "Return a Pedido web to the queue", "description": "Sends a taken Pedido web back to the queue (MER-5431): only its claim clears, so its Reservas, frozen terms, version and deadline stay identical. Its claimant returns it, and so does a holder of backoffice.sales.web-orders.release; another cashier answers 409 web_order_claim_conflict. It reads no Turno, so it works after the shift closed, and it carries no expected_version, so a buyer's rail change does not stop it. The same key, actor and body replays 200 with the same bytes; the same key with another body or actor answers 409 idempotency_key_conflict; a refused attempt burns no key. Requires backoffice.sales.web-orders.claim; a POS session token reaches it. Answers Cache-Control: private, no-store.", "operationId": "returnPosWebOrder", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderReturnRequest" } } } }, "responses": { "200": { "description": "The order with claim null, on the first time and on every replay", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderQueueCommandResult" } } } }, "401": { "description": "Unauthenticated: the auth middleware answers before the controller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderMiddlewareMessage" } } } }, "403": { "description": "Without backoffice.sales.web-orders.claim, or a caller who does not belong to the company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderQueueProblem" } } } }, "404": { "description": "cash_register_not_found; web_order_not_found: unknown, or of another company or Location, the same answer for each; a malformed id matches no route (message only)", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/WebOrderQueueProblem" }, { "$ref": "#/components/schemas/WebOrderMiddlewareMessage" } ] } } } }, "409": { "description": "web_order_not_claimed: unclaimed, or already returned under a new key; web_order_claim_conflict: a stale cycle or another cashier's claim (each with order_status, current_version, expires_at and claim); idempotency_key_conflict; web_order_already_charged (with charged_sale): a till charged it, so this names its sale", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderQueueProblem" } } } }, "422": { "description": "The body failed its rules (errors names each field); or counter_sale_cash_register_not_selling (with reason)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderQueueProblem" } } } }, "500": { "description": "Unexpected, reported: a lost race the three attempts did not settle. Resend the same key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderQueueProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/pos/web-orders/{id}/take-over": { "post": { "tags": [ "Backoffice - Sales - Web Orders" ], "summary": "Take over a Pedido web whose claim's Turno closed", "description": "Takes over a Pedido web whose claim was made on a Turno that is now closed (MER-5433), so no claim strands an unpaid order. Any holder of backoffice.sales.web-orders.claim on an open Turno of a Caja selling at the order's Location may take it, its former holder included; the till names the claim_cycle_id and the version it saw. The new claimant is the session's user and the shift is the Caja's open Turno, locked; any such key in the body is ignored. A new claim_cycle_id is issued, so a till that saw the old claim gets web_order_claim_conflict from charge, return and release. Only claim metadata moves: its version, status, Reservas, frozen terms and deadline stay. Lock order: the Caja's Turno, the order, the key, and only then a plain read of the claim's Turno, which is never locked. A Turno only goes from open to closed, so a read that says closed stays true; a read whose snapshot predates the close says open and answers web_order_already_claimed, and resending (a new attempt reads again) succeeds. The same key, actor and body replays 200 with the same bytes, before the old Turno is read; the same key with another body, actor or command answers 409 idempotency_key_conflict; a refused attempt burns no key. A replay after the taker's Turno closed answers cash_shift_not_open. Requires backoffice.sales.web-orders.claim; a POS session token reaches it. Answers Cache-Control: private, no-store.", "operationId": "takeOverPosWebOrder", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderTakeOverRequest" } } } }, "responses": { "200": { "description": "The new claim, on the first time and on every replay", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderQueueCommandResult" } } } }, "401": { "description": "Unauthenticated: the auth middleware answers before the controller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderMiddlewareMessage" } } } }, "403": { "description": "Without backoffice.sales.web-orders.claim, or a caller who does not belong to the company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderQueueProblem" } } } }, "404": { "description": "cash_register_not_found; web_order_not_found: unknown, or of another company or Location, the same answer for each; a malformed id matches no route (message only)", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/WebOrderQueueProblem" }, { "$ref": "#/components/schemas/WebOrderMiddlewareMessage" } ] } } } }, "409": { "description": "cash_shift_not_open (with cash_register_id): the Caja has no open Turno, also on a replay after it closed; web_order_already_charged (with charged_sale): a till charged it, so this names its sale; web_order_expired, web_order_not_claimable, web_order_version_conflict: its state or version; web_order_not_claimed: nobody holds it now; web_order_claim_conflict: it holds another cycle than the one sent; web_order_already_claimed: its Turno is not proved closed, either still open or closed after this attempt's read, so read it again (each of these with order_status, current_version, expires_at and claim); idempotency_key_conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderQueueProblem" } } } }, "422": { "description": "The body failed its rules (errors names each field); or counter_sale_cash_register_not_selling (with reason)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderQueueProblem" } } } }, "500": { "description": "Unexpected, reported: a lost race the three attempts did not settle. Resend the same key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderQueueProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/sales/web-orders": { "get": { "tags": [ "Backoffice - Sales - Web Orders" ], "summary": "List Pedidos web", "description": "The Pedidos web inbox (MER-5429): one page of the company's orders. Send status=payment_reported for the default tab. For an all-statuses tab use sort_by=created_at&sort_order=desc, because review_due_at nulls sort first. Ties break by id in the same direction. Blank values are absent. Requires backoffice.sales.web-orders.view. Answers Cache-Control: private, no-store. The buyer's phone never appears.", "operationId": "d403aa7583e8b8d217cb0a94faa784bd", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "awaiting_payment", "payment_reported", "approved", "rejected", "cancelled", "expired", "charged_in_store" ] } }, { "name": "sort_by", "in": "query", "required": false, "schema": { "type": "string", "default": "review_due_at", "enum": [ "review_due_at", "created_at" ] } }, { "name": "sort_order", "in": "query", "required": false, "schema": { "type": "string", "default": "asc", "enum": [ "asc", "desc" ] } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 25, "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "The page", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderReviewPage" } } } }, "401": { "description": "Unauthenticated: the auth middleware answers before the controller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderMiddlewareMessage" } } } }, "403": { "description": "Without backoffice.sales.web-orders.view (error_code null), or a tenant the caller does not belong to (no error_code at all)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderReviewProblem" } } } }, "422": { "description": "A parameter is invalid (errors names it)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderReviewProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/security/api-keys/{id}": { "delete": { "tags": [ "Backoffice - Security - API Keys" ], "summary": "Revoke a company API key", "operationId": "c6ef904969db02311f0f2f4b102fb954", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "204": { "description": "API key revoked" }, "403": { "description": "Forbidden or bearer-token authentication" }, "404": { "description": "API key not found" }, "422": { "description": "The id is not a positive integer: errors.id" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "cookieAuth": [] } ] } }, "/api/backoffice/{tenant}/security/api-keys": { "get": { "tags": [ "Backoffice - Security - API Keys" ], "summary": "List the current company's managed API keys", "operationId": "55189d9daa274df836e341e1fa77116c", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Tenant-scoped API key list", "content": { "application/json": { "schema": { "required": [ "api_keys" ], "properties": { "api_keys": { "type": "array", "items": { "required": [ "id", "name", "owner", "read_only", "expires_at", "last_used_at", "created_at" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "owner": { "required": [ "id", "name" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "type": "object" }, "read_only": { "type": "boolean" }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "last_used_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" } } }, "type": "object" } } } }, "403": { "description": "Forbidden or bearer-token authentication" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "cookieAuth": [] } ] }, "post": { "tags": [ "Backoffice - Security - API Keys" ], "summary": "Create an API key for the authenticated user", "operationId": "5023479ed7e59e76f04efa501944cdda", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "read_only" ], "properties": { "name": { "type": "string", "example": "wacrm" }, "expiration_preset": { "type": "string", "default": "1_year", "enum": [ "30_days", "1_year", "none" ] }, "read_only": { "description": "Whether the key is limited to the read ability. Send a JSON boolean; 1 and 0, as numbers or strings, are read as true and false.", "type": "boolean", "example": false } }, "type": "object" } } } }, "responses": { "201": { "description": "API key created; plaintext is returned once", "content": { "application/json": { "schema": { "required": [ "api_key", "plain_text_token" ], "properties": { "api_key": { "required": [ "id", "name", "owner", "read_only", "expires_at", "last_used_at", "created_at" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "owner": { "required": [ "id", "name" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "type": "object" }, "read_only": { "type": "boolean" }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "last_used_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "plain_text_token": { "description": "One-time plaintext credential; it is never returned by list responses.", "type": "string" } }, "type": "object" } } } }, "403": { "description": "Forbidden or bearer-token authentication" }, "422": { "description": "Validation error" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "cookieAuth": [] } ] } }, "/api/backoffice/{tenant}/security/contexts": { "get": { "tags": [ "Backoffice - Security - Contexts" ], "summary": "Get all available contexts", "operationId": "024b3c095bd62e30777aade38ed39d28", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful retrieval of contexts list", "content": { "application/json": { "schema": { "properties": { "contexts": { "type": "array", "items": { "properties": { "id": { "type": "string", "example": "accounting" }, "name": { "type": "string", "example": "Accounting" } }, "type": "object" } } }, "type": "object" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unauthorized" }, "status": { "type": "integer", "example": 403 }, "detail": { "type": "string", "example": "You do not have permission to view this resource." } }, "type": "object" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Internal Server Error" }, "detail": { "type": "string", "example": "An unexpected error occurred" }, "status": { "type": "integer", "example": 500 } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/security/modules": { "get": { "tags": [ "Backoffice - Security - Modules" ], "summary": "Get modules for a specific context", "operationId": "882ec7edd8be197493491f4265c80521", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant ID", "required": true, "schema": { "type": "string" } }, { "name": "context_id", "in": "query", "description": "The context ID to get modules for", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful retrieval of modules list", "content": { "application/json": { "schema": { "properties": { "modules": { "type": "array", "items": { "properties": { "id": { "type": "string", "example": "roles" }, "name": { "type": "string", "example": "Roles" } }, "type": "object" } } }, "type": "object" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Bad Request" }, "status": { "type": "integer", "example": 400 }, "detail": { "type": "string", "example": "Context ID is required" } }, "type": "object" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unauthorized" }, "status": { "type": "integer", "example": 403 }, "detail": { "type": "string", "example": "You do not have permission to view this resource." } }, "type": "object" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Internal Server Error" }, "detail": { "type": "string", "example": "An unexpected error occurred" }, "status": { "type": "integer", "example": 500 } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/security/permissions": { "get": { "tags": [ "Backoffice - Security - Permissions" ], "summary": "Get permissions for a specific module and role", "operationId": "e19c27cf0e68743faac3cc91b6b0eeb7", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant ID", "required": true, "schema": { "type": "string" } }, { "name": "module_id", "in": "query", "description": "The module ID to get permissions for", "required": true, "schema": { "type": "string" } }, { "name": "role_id", "in": "query", "description": "The role ID to check permissions against", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Successful retrieval of permissions list", "content": { "application/json": { "schema": { "properties": { "permissions": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "backoffice.security.roles.view" }, "label": { "type": "string", "example": "View roles" }, "has_permission": { "type": "boolean", "example": true } }, "type": "object" } } }, "type": "object" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Bad Request" }, "status": { "type": "integer", "example": 400 }, "detail": { "type": "string", "example": "Module ID is required" } }, "type": "object" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unauthorized" }, "status": { "type": "integer", "example": 403 }, "detail": { "type": "string", "example": "You do not have permission to view this resource." } }, "type": "object" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Internal Server Error" }, "detail": { "type": "string", "example": "An unexpected error occurred" }, "status": { "type": "integer", "example": 500 } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/security/role-permissions": { "post": { "tags": [ "Backoffice - Security - Role Permissions" ], "summary": "Attach a permission to a role", "operationId": "40cb5e97f8ffc772c1aa3b1010d3eba9", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "role_id", "permission_id" ], "properties": { "role_id": { "description": "The role being granted a permission (subject of the mutation). Another company's role or an unknown id answers 404 role_not_found.", "type": "integer", "example": 1 }, "permission_id": { "description": "A Backoffice catalog permission id. Unknown or out-of-catalog ids answer 422 on permission_id (permission_not_grantable).", "type": "integer", "example": 2 } }, "type": "object" } } } }, "responses": { "200": { "description": "Permission attached to role successfully" }, "422": { "description": "Field validation errors under errors, keyed by role_id and permission_id; out-of-catalog permission_id may also carry error_code permission_not_grantable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsersAndRolesProblem" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unauthorized" }, "status": { "type": "integer", "example": 403 }, "detail": { "type": "string", "example": "You do not have permission to view this resource." } }, "type": "object" } } } }, "404": { "description": "Role not found for this company (foreign or unknown role_id)", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "detail": { "type": "string", "example": "El rol con el id 1 no existe." }, "error_code": { "type": "string", "example": "role_not_found" } }, "type": "object" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Internal Server Error" }, "status": { "type": "integer", "example": 500 }, "detail": { "type": "string", "example": "An unexpected error occurred while processing your request." } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Backoffice - Security - Role Permissions" ], "summary": "Detach a permission from a role", "operationId": "9e1a568400ce67cb9186280685184556", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "role_id", "permission_id" ], "properties": { "role_id": { "description": "The role being revoked a permission (subject of the mutation). Another company's role or an unknown id answers 404 role_not_found.", "type": "integer", "example": 1 }, "permission_id": { "description": "A Backoffice catalog permission id. Unknown or out-of-catalog ids answer 422 on permission_id (permission_not_grantable).", "type": "integer", "example": 2 } }, "type": "object" } } } }, "responses": { "200": { "description": "Permission detached from role successfully" }, "422": { "description": "Field validation errors under errors, keyed by role_id and permission_id; out-of-catalog permission_id may also carry error_code permission_not_grantable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsersAndRolesProblem" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unauthorized" }, "status": { "type": "integer", "example": 403 }, "detail": { "type": "string", "example": "You do not have permission to view this resource." } }, "type": "object" } } } }, "404": { "description": "Role not found for this company (foreign or unknown role_id), or the role-permission pair is not granted (role_permission_not_found)", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "detail": { "type": "string", "example": "El permiso del rol no fue encontrado" }, "error_code": { "type": "string", "example": "role_permission_not_found" } }, "type": "object" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Internal Server Error" }, "status": { "type": "integer", "example": 500 }, "detail": { "type": "string", "example": "An unexpected error occurred while processing your request." } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/security/role-templates": { "get": { "tags": [ "Backoffice - Security - Role Templates" ], "summary": "List the role templates", "description": "Every role template with the permissions it grants today, resolved against the permission catalog. A role created from a template (POST /security/roles/from-template) receives exactly these permissions. Not paginated: the catalog is defined in code.", "operationId": "9a8a6f493fce5e1c221feb3ab1923c68", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The role templates", "content": { "application/json": { "schema": { "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "required": [ "code", "name", "description", "permissions", "permissions_count" ], "properties": { "code": { "type": "string", "example": "contador" }, "name": { "type": "string", "example": "Contador" }, "description": { "type": "string", "example": "Contabilidad completa sin eliminar; consulta, aprobación y anulación de documentos" }, "permissions": { "type": "array", "items": { "type": "string", "example": "backoffice.accounting.manual-entries.view" } }, "permissions_count": { "type": "integer", "example": 114 } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "403": { "description": "Without backoffice.security.roles.view", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Forbidden" }, "status": { "type": "integer", "example": 403 }, "detail": { "type": "string", "example": "You do not have permission to access this resource." }, "error_code": { "type": "string", "example": null, "nullable": true } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/security/roles/from-template": { "post": { "tags": [ "Backoffice - Security - Roles" ], "summary": "Create a role from a role template", "description": "Creates a role and grants it every permission the template resolves to, in one transaction. Requires both backoffice.security.roles.create and backoffice.security.role-permissions.create. The role takes the template's name unless `name` is given, and the template's description. It is never Superadmin and is not assigned to any user; its permissions stay editable afterwards. Role names compare case- and accent-insensitively within the company.", "operationId": "f4df25cb501d91fb2f827aad3a3ad143", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "template" ], "properties": { "template": { "description": "A template code listed by GET /security/role-templates", "type": "string", "example": "contador" }, "name": { "description": "The role's name; the template's name when omitted or null.", "type": "string", "example": "Contador externo", "nullable": true, "maxLength": 80, "minLength": 3 } }, "type": "object" } } } }, "responses": { "201": { "description": "Role created with the template's permissions", "content": { "application/json": { "schema": { "required": [ "id" ], "properties": { "id": { "type": "integer", "example": 42 } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "403": { "description": "Without backoffice.security.roles.create or backoffice.security.role-permissions.create", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unauthorized" }, "status": { "type": "integer", "example": 403 }, "detail": { "type": "string", "example": "You do not have permission to access this resource." }, "error_code": { "type": "string", "example": null, "nullable": true } }, "type": "object" } } } }, "404": { "description": "role_template_not_found: no template has that code", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "detail": { "type": "string", "example": "No existe la plantilla de rol «superadmin»." }, "error_code": { "type": "string", "example": "role_template_not_found", "nullable": true } }, "type": "object" } } } }, "409": { "description": "role_name_already_exists: the company already has a role with that name", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "detail": { "type": "string", "example": "Ya existe un rol llamado «Contador» en esta empresa." }, "error_code": { "type": "string", "example": "role_name_already_exists", "nullable": true } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string", "example": "The given data was invalid." }, "error_code": { "type": "string", "example": null, "nullable": true }, "errors": { "type": "object" } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/security/roles/{id}": { "get": { "tags": [ "Backoffice - Security - Roles" ], "summary": "Get a role by ID", "description": "Returns the details of a role based on the provided ID.", "operationId": "404c5d205f7229ece33e78acd5f06180", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "The ID of the role to retrieve", "required": true, "schema": { "type": "integer", "example": 1, "minimum": 1 } } ], "responses": { "200": { "description": "The role with its member count and administrator flag", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Role" } } } }, "422": { "description": "The id is not a positive integer: errors.id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsersAndRolesProblem" } } } }, "404": { "description": "The role does not exist or belongs to another company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsersAndRolesProblem" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unauthorized" }, "status": { "type": "integer", "example": 403 }, "detail": { "type": "string", "example": "You do not have permission to view this resource." } }, "type": "object" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Internal Server Error" }, "status": { "type": "integer", "example": 500 }, "detail": { "type": "string", "example": "An unexpected error occurred." } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Backoffice - Security - Roles" ], "summary": "Update an existing role", "description": "Updates an existing role with the provided details.", "operationId": "8f20ff2d204fa10090e08954d6c90c15", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "The ID of the role to update", "required": true, "schema": { "type": "integer", "example": 1, "minimum": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "status" ], "properties": { "name": { "description": "The name of the role.", "type": "string", "example": "Updated Role Name", "maxLength": 80, "minLength": 3 }, "description": { "description": "A brief description of the role.", "type": "string", "example": "Updated role description", "nullable": true, "maxLength": 100, "minLength": 3 }, "status": { "description": "Role status, trimmed and compared without letter case. The upper-case spelling (ACTIVE, INACTIVE) is deprecated and still accepted; any other value answers 422.", "type": "string", "example": "inactive", "enum": [ "active", "inactive" ] } }, "type": "object" } } } }, "responses": { "200": { "description": "Role updated successfully", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Role updated successfully." } }, "type": "object" } } } }, "422": { "description": "Field validation errors under errors, keyed by id, name, description and status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsersAndRolesProblem" } } } }, "404": { "description": "Role not found", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "detail": { "type": "string", "example": "El rol con el id 42 no existe." } }, "type": "object" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unauthorized" }, "status": { "type": "integer", "example": 403 }, "detail": { "type": "string", "example": "You do not have permission to update this resource." } }, "type": "object" } } } }, "409": { "description": "The company already has a role with that name (names compare case- and accent-insensitively): role_name_already_exists, with the reason also under errors.name", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsersAndRolesProblem" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Internal Server Error" }, "status": { "type": "integer", "example": 500 }, "detail": { "type": "string", "example": "An unexpected error occurred while processing your request." } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/security/roles": { "get": { "tags": [ "Backoffice - Security - Roles" ], "summary": "List the company's roles", "description": "Roles of the company with their members and states. Unknown query keys are ignored.", "operationId": "6e26d9d413a5c08234a519a0d609cb28", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 100, "minimum": 1 } }, { "name": "search", "in": "query", "description": "Name, matched literally; empty means omitted.", "required": false, "schema": { "type": "string", "maxLength": 255 } }, { "name": "name", "in": "query", "description": "Name, matched literally; empty means omitted.", "required": false, "schema": { "type": "string", "maxLength": 255 } }, { "name": "status", "in": "query", "description": "Omitted, empty or all means every state.", "required": false, "schema": { "type": "string", "enum": [ "active", "inactive", "all" ] } }, { "name": "status[]", "in": "query", "description": "Roles in any of these states; all is not a list member.", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "active", "inactive" ] } } }, { "name": "sort_by", "in": "query", "description": "Default name ascending; a field without sort_order reads descending. The role id breaks ties in the same direction.", "required": false, "schema": { "type": "string", "default": "name", "enum": [ "name", "created_at" ] } }, { "name": "sort_order", "in": "query", "description": "Trimmed and case-insensitive.", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "group_by", "in": "query", "description": "status orders active before inactive, before the selected sort and before paging.", "required": false, "schema": { "type": "string", "enum": [ "status", "none" ] } } ], "responses": { "200": { "description": "A page of company roles with the roles per state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RolesPage" } } } }, "422": { "description": "Field validation errors under errors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsersAndRolesProblem" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unauthorized" }, "status": { "type": "integer", "example": 403 }, "detail": { "type": "string", "example": "You do not have permission to view this resource." } }, "type": "object" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Internal Server Error" }, "detail": { "type": "string", "example": "An unexpected error occurred" }, "status": { "type": "integer", "example": 500 } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Security - Roles" ], "summary": "Create a new role", "description": "Creates a new role with the provided details.", "operationId": "a8dca705db1e999af5f9c773df6919ae", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name" ], "properties": { "name": { "description": "The name of the role.", "type": "string", "example": "Admin", "maxLength": 80, "minLength": 3 }, "description": { "description": "A brief description of the role.", "type": "string", "example": "Administrator role", "nullable": true, "maxLength": 100, "minLength": 3 } }, "type": "object" } } } }, "responses": { "201": { "description": "Role created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatedRecordId" } } } }, "422": { "description": "Field validation errors under errors, keyed by name and description", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsersAndRolesProblem" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unauthorized" }, "status": { "type": "integer", "example": 403 }, "detail": { "type": "string", "example": "You do not have permission to create this resource." } }, "type": "object" } } } }, "409": { "description": "The company already has a role with that name (names compare case- and accent-insensitively): role_name_already_exists, with the reason also under errors.name", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsersAndRolesProblem" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Internal Server Error" }, "status": { "type": "integer", "example": 500 }, "detail": { "type": "string", "example": "An unexpected error occurred while processing your request." } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/treasury/bank-reconciliation-accounts": { "get": { "tags": [ "Backoffice - Treasury - Bank Reconciliations" ], "summary": "List which treasury accounts can be reconciled", "description": "Every treasury account of the company, active ones first, then by name: reconcilable when no other active treasury account shares its accounting account and currency (ADR 0267), and otherwise naming those accounts. A bounded per-company list, so it is not paged. Each account carries its start month and closed-through month, read for every account at once. Requires `backoffice.treasury.bank-reconciliations.view`.", "operationId": "searchBankReconciliationAccounts", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The accounts", "content": { "application/json": { "schema": { "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/BankReconciliationAccountResource" } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankStatementMessageError" } } } }, "403": { "description": "The user lacks the view permission, or the API key scope or tenant membership refuses the request", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/BankStatementProblem" }, { "$ref": "#/components/schemas/BankStatementMiddlewareProblem" } ] } } } }, "404": { "description": "The tenant is unknown", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/BankStatementProblem" }, { "$ref": "#/components/schemas/BankStatementMessageError" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/treasury/accounts/{treasuryAccountId}/bank-reconciliations/{month}/close": { "post": { "tags": [ "Backoffice - Treasury - Bank Reconciliations" ], "summary": "Close a month of a treasury account's bank reconciliation", "description": "Closes the month on its proof (ADR 0268), storing its four figures and who closed it, opens the next month's row, and is audited as `backoffice.treasury.bank-reconciliations.closed`. The refusals come in this order: the account shares its accounting account and currency (422 treasury_account_not_reconcilable); its reconciliation has not started or starts after the month (422 bank_reconciliation_not_started, with start_month); the month is already closed (409); the month before is not closed and this is not the start month (422 bank_reconciliation_out_of_order); the month has not ended in the company's time zone (422 bank_reconciliation_month_not_ended); the bank's closing balance is not the sum of the statement lines through the month's end (422 statement_lines_incomplete, with both figures); the proof leaves a difference (422 bank_reconciliation_unbalanced, with its figures). A missing attachment never keeps a month from closing. Once closed, a match whose lines are all dated on or before the month's end can be neither made nor undone, and an import's rows dated in it are errors. Requires `backoffice.treasury.bank-reconciliations.close`.", "operationId": "closeBankReconciliation", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "treasuryAccountId", "in": "path", "description": "The treasury account", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "month", "in": "path", "description": "The month to close, YYYY-MM", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$", "example": "2026-09" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "statement_closing_balance" ], "properties": { "statement_closing_balance": { "description": "The closing balance the bank printed for the month, signed, up to two decimals.", "type": "string", "pattern": "^-?\\d{1,13}(\\.\\d{1,2})?$", "example": "106600.00" } }, "type": "object" } } } }, "responses": { "200": { "description": "The month, closed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankReconciliationResource" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankStatementMessageError" } } } }, "403": { "description": "The user lacks the close permission, or the API key scope or tenant membership refuses the request", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/BankStatementProblem" }, { "$ref": "#/components/schemas/BankStatementMiddlewareProblem" } ] } } } }, "404": { "description": "The treasury account (bank_reconciliation_treasury_account_not_found) or the company (company_not_found) does not exist, or the tenant is unknown", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/BankStatementProblem" }, { "$ref": "#/components/schemas/BankStatementMessageError" } ] } } } }, "409": { "description": "The month is already closed (bank_reconciliation_already_closed, with month and closed_through)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankReconciliationMonthStateProblem" } } } }, "422": { "description": "Validation error (errors.month, errors.statement_closing_balance), the account shares its accounting account and currency (treasury_account_not_reconcilable), its reconciliation has not started or starts after the month (bank_reconciliation_not_started, with start_month), the month before is not closed (bank_reconciliation_out_of_order, with month and expected_month), the month has not ended (bank_reconciliation_month_not_ended, with month), the bank's closing balance is not the statement lines' sum (statement_lines_incomplete, with currency, statement_closing_balance, statement_balance and difference), the proof does not balance (bank_reconciliation_unbalanced, with currency, statement_balance, statement_outstanding_total, book_balance, book_outstanding_total and difference), or a side holds more than 2000 outstanding lines (bank_reconciliation_proof_too_many_lines)", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/BankStatementProblem" }, { "$ref": "#/components/schemas/TreasuryAccountNotReconcilableProblem" }, { "$ref": "#/components/schemas/BankReconciliationNotStartedProblem" }, { "$ref": "#/components/schemas/BankReconciliationOutOfOrderProblem" }, { "$ref": "#/components/schemas/BankReconciliationMonthProblem" }, { "$ref": "#/components/schemas/StatementLinesIncompleteProblem" }, { "$ref": "#/components/schemas/BankReconciliationUnbalancedProblem" }, { "$ref": "#/components/schemas/BankReconciliationProofTooManyLinesProblem" } ] } } } }, "500": { "description": "A ledger line moves units with no side (reconciliation_ledger_line_unsided), or the account's stored reconciliation rows are corrupt (invalid_bank_reconciliation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankStatementProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/treasury/accounts/{treasuryAccountId}/bank-reconciliations/{month}": { "get": { "tags": [ "Backoffice - Treasury - Bank Reconciliations" ], "summary": "Read a month's bank reconciliation proof", "description": "The month's proof (ADR 0268), computed on every read: the statement's balance (its lines from the start month's first day through the month's end, the opening line included) and the books' balance at the month's end, each with what it holds outstanding, and the difference (statement balance − statement outstanding) − (book balance − book outstanding). A line is reconciled at the month's end only when every line of its active match is dated on or before it; a line held by a match reaching into a later month stays outstanding with that match's id. The books' balance before the start is its own object, outstanding while no match reconciles it and it is not zero. A month with no row yet is still read, with `reconciliation` null. For a closed month, the live figures may differ from those its close stored, which `reconciliation` keeps. Each side lists at most 2000 outstanding lines. Requires `backoffice.treasury.bank-reconciliations.view`.", "operationId": "findBankReconciliationProof", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "treasuryAccountId", "in": "path", "description": "The treasury account", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "month", "in": "path", "description": "The month, YYYY-MM", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$", "example": "2026-09" } } ], "responses": { "200": { "description": "The proof", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankReconciliationProofResource" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankStatementMessageError" } } } }, "403": { "description": "The user lacks the view permission, or the API key scope or tenant membership refuses the request", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/BankStatementProblem" }, { "$ref": "#/components/schemas/BankStatementMiddlewareProblem" } ] } } } }, "404": { "description": "The treasury account (bank_reconciliation_treasury_account_not_found) or the company (company_not_found) does not exist, or the tenant is unknown", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/BankStatementProblem" }, { "$ref": "#/components/schemas/BankStatementMessageError" } ] } } } }, "422": { "description": "Validation error (errors.month), the account shares its accounting account and currency (treasury_account_not_reconcilable, with conflicting_treasury_accounts), its reconciliation has not started or starts after the month (bank_reconciliation_not_started, with start_month), or a side holds more than 2000 outstanding lines (bank_reconciliation_proof_too_many_lines, with side and limit)", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/BankStatementProblem" }, { "$ref": "#/components/schemas/TreasuryAccountNotReconcilableProblem" }, { "$ref": "#/components/schemas/BankReconciliationNotStartedProblem" }, { "$ref": "#/components/schemas/BankReconciliationProofTooManyLinesProblem" } ] } } } }, "500": { "description": "A ledger line moves units with no side (reconciliation_ledger_line_unsided), or the account's stored reconciliation rows are corrupt (invalid_bank_reconciliation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankStatementProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/treasury/accounts/{treasuryAccountId}/bank-reconciliations/{month}/reopen": { "post": { "tags": [ "Backoffice - Treasury - Bank Reconciliations" ], "summary": "Reopen the latest closed month of a treasury account's bank reconciliation", "description": "Reopens the closed-through month (ADR 0268) so its matches and imports thaw; the month before it becomes the closed-through month, or none stays closed when it was the only one. Only the closed-through month reopens, so the closed months stay one run. The row keeps the figures of its close and who closed it, though the response shows them only while closed; it records who reopened it, when and why, and the reopening is audited as `backoffice.treasury.bank-reconciliations.reopened`. Requires `backoffice.treasury.bank-reconciliations.reopen`; the close permission alone is not enough.", "operationId": "reopenBankReconciliation", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "treasuryAccountId", "in": "path", "description": "The treasury account", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "month", "in": "path", "description": "The month to reopen, YYYY-MM", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$", "example": "2026-09" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "reason" ], "properties": { "reason": { "description": "Why the month reopens. Surrounding whitespace is trimmed first and the 1 to 500 characters are counted on what remains; inner line breaks are kept and a blank reason is refused.", "type": "string", "example": "Faltaba una comisión del banco", "maxLength": 500, "minLength": 1 } }, "type": "object" } } } }, "responses": { "200": { "description": "The month, open again", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankReconciliationResource" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankStatementMessageError" } } } }, "403": { "description": "The user lacks the reopen permission, or the API key scope or tenant membership refuses the request", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/BankStatementProblem" }, { "$ref": "#/components/schemas/BankStatementMiddlewareProblem" } ] } } } }, "404": { "description": "The treasury account does not exist in this company (bank_reconciliation_treasury_account_not_found), or the tenant is unknown", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/BankStatementProblem" }, { "$ref": "#/components/schemas/BankStatementMessageError" } ] } } } }, "422": { "description": "Validation error (errors.month, errors.reason), the account's reconciliation has not started or starts after the month (bank_reconciliation_not_started, with start_month), the month is open (bank_reconciliation_not_closed, with month), or it is closed but is not the closed-through month (bank_reconciliation_not_latest_closed, with month and closed_through)", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/BankStatementProblem" }, { "$ref": "#/components/schemas/BankReconciliationNotStartedProblem" }, { "$ref": "#/components/schemas/BankReconciliationMonthProblem" }, { "$ref": "#/components/schemas/BankReconciliationMonthStateProblem" } ] } } } }, "500": { "description": "The account's stored reconciliation rows are corrupt (invalid_bank_reconciliation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankStatementProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/treasury/accounts/{treasuryAccountId}/bank-reconciliations/start/correction": { "post": { "tags": [ "Backoffice - Treasury - Bank Reconciliations" ], "summary": "Correct a treasury account's bank reconciliation start", "description": "Corrects the account's bank reconciliation start month and statement opening balance (ADR 0305) while no month is closed and the opening line is unmatched, with a reason of 1 to 500 characters. Moves the start month's row, rewrites the opening line in place (same id and fingerprint), and appends a correction record. Audited as `backoffice.treasury.bank-reconciliations.start-corrected`. Requires `backoffice.treasury.bank-reconciliations.manage`.", "operationId": "correctBankReconciliationStart", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "treasuryAccountId", "in": "path", "description": "The treasury account", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "start_month", "statement_opening_balance", "reason" ], "properties": { "start_month": { "description": "The corrected first month to reconcile, YYYY-MM.", "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$", "example": "2026-09" }, "statement_opening_balance": { "description": "The corrected balance the statement opens the month with, signed, up to two decimals; it may be zero or negative.", "type": "string", "pattern": "^-?\\d{1,13}(\\.\\d{1,2})?$", "example": "1250.00" }, "reason": { "description": "Why the start is corrected: 1 to 500 characters after Unicode trim.", "type": "string", "example": "El mes de inicio del extracto era septiembre", "maxLength": 500 } }, "type": "object" } } } }, "responses": { "200": { "description": "The start was corrected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankReconciliationStartCorrectedResource" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankStatementMessageError" } } } }, "403": { "description": "The user lacks the manage permission, or the API key scope or tenant membership refuses the request", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/BankStatementProblem" }, { "$ref": "#/components/schemas/BankStatementMiddlewareProblem" } ] } } } }, "404": { "description": "The treasury account (bank_reconciliation_treasury_account_not_found) or the company (company_not_found) does not exist, or the tenant is unknown", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/BankStatementProblem" }, { "$ref": "#/components/schemas/BankStatementMessageError" } ] } } } }, "409": { "description": "Not started (bank_reconciliation_not_started), a month is closed (bank_reconciliation_has_closed_months, with closed_through), the opening line is matched (bank_reconciliation_opening_line_matched, with match_ids), or active matches span the new start (bank_reconciliation_start_splits_matches, with match_ids)", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/BankStatementProblem" }, { "$ref": "#/components/schemas/BankReconciliationHasClosedMonthsProblem" }, { "$ref": "#/components/schemas/BankReconciliationOpeningLineMatchedProblem" }, { "$ref": "#/components/schemas/BankReconciliationStartSplitsMatchesProblem" } ] } } } }, "422": { "description": "Validation error, the account is not reconcilable, the start month is in the future, the start is unchanged, or the reason is invalid", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/BankStatementProblem" }, { "$ref": "#/components/schemas/TreasuryAccountNotReconcilableProblem" }, { "$ref": "#/components/schemas/BankReconciliationStartMonthInFutureProblem" }, { "$ref": "#/components/schemas/BankReconciliationStartUnchangedProblem" }, { "$ref": "#/components/schemas/InvalidBankReconciliationStartCorrectionReasonProblem" } ] } } } }, "500": { "description": "The account's stored reconciliation rows are corrupt (invalid_bank_reconciliation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankStatementProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/treasury/accounts/{treasuryAccountId}/bank-reconciliations/start": { "post": { "tags": [ "Backoffice - Treasury - Bank Reconciliations" ], "summary": "Start a treasury account's bank reconciliation", "description": "Starts the account's bank reconciliation once (ADR 0268): writes the start month's row, open, and an `opening` Bank Statement Line dated its first day carrying the statement's opening balance, which matches like any line, against ledger lines such as an opening entry or against the book balance before the start (`pre_start_balance` on a match). The start month must have begun in the company's time zone. A start is refused while an active match holds lines dated both before and from the start month. A second start answers 409 with the start month, so a client retrying its own call can tell. Requires `backoffice.treasury.bank-reconciliations.manage`.", "operationId": "startBankReconciliation", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "treasuryAccountId", "in": "path", "description": "The treasury account", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "start_month", "statement_opening_balance" ], "properties": { "start_month": { "description": "The first month to reconcile, YYYY-MM.", "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$", "example": "2026-09" }, "statement_opening_balance": { "description": "The balance the statement opens the month with, signed, up to two decimals; it may be zero or negative.", "type": "string", "pattern": "^-?\\d{1,13}(\\.\\d{1,2})?$", "example": "100000.00" } }, "type": "object" } } } }, "responses": { "201": { "description": "The reconciliation started", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankReconciliationStartedResource" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankStatementMessageError" } } } }, "403": { "description": "The user lacks the manage permission, or the API key scope or tenant membership refuses the request", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/BankStatementProblem" }, { "$ref": "#/components/schemas/BankStatementMiddlewareProblem" } ] } } } }, "404": { "description": "The treasury account (bank_reconciliation_treasury_account_not_found) or the company (company_not_found) does not exist, or the tenant is unknown", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/BankStatementProblem" }, { "$ref": "#/components/schemas/BankStatementMessageError" } ] } } } }, "409": { "description": "The reconciliation already started (bank_reconciliation_already_started, with start_month), or active matches hold lines on both sides of the start (bank_reconciliation_start_splits_matches, with match_ids)", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/BankReconciliationAlreadyStartedProblem" }, { "$ref": "#/components/schemas/BankReconciliationStartSplitsMatchesProblem" } ] } } } }, "422": { "description": "Validation error (errors.start_month, errors.statement_opening_balance), the account shares its accounting account and currency (treasury_account_not_reconcilable, with conflicting_treasury_accounts), or the start month comes after the current month (bank_reconciliation_start_month_in_future, with current_month)", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/BankStatementProblem" }, { "$ref": "#/components/schemas/TreasuryAccountNotReconcilableProblem" }, { "$ref": "#/components/schemas/BankReconciliationStartMonthInFutureProblem" } ] } } } }, "500": { "description": "The account's stored reconciliation rows are corrupt (invalid_bank_reconciliation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankStatementProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/treasury/bank-statement-import-profiles/{id}": { "get": { "tags": [ "Backoffice - Treasury - Bank Statement Import Profiles" ], "summary": "Get a bank statement import profile", "description": "Requires `backoffice.treasury.bank-reconciliations.view`.", "operationId": "findBankStatementImportProfile", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "The profile id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The profile", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankStatementImportProfileResource" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankStatementMessageError" } } } }, "403": { "description": "The user lacks the view permission, or the API key scope or tenant membership refuses the request", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/BankStatementProblem" }, { "$ref": "#/components/schemas/BankStatementMiddlewareProblem" } ] } } } }, "404": { "description": "The profile does not exist in this company (bank_statement_import_profile_not_found), or the tenant is unknown", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/BankStatementProblem" }, { "$ref": "#/components/schemas/BankStatementMessageError" } ] } } } }, "422": { "description": "The id is not a UUID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankStatementProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Backoffice - Treasury - Bank Statement Import Profiles" ], "summary": "Update a bank statement import profile", "description": "Replaces the name and the layout of a profile, with the rules of the create. Changing the reference, description or balance column changes the Statement Fingerprint of the lines imported afterwards, so duplicates across the change are no longer detected. Requires `backoffice.treasury.bank-reconciliations.manage`.", "operationId": "updateBankStatementImportProfile", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "The profile id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "format", "header_row", "number_format", "amount_mode", "columns" ], "properties": { "name": { "type": "string", "example": "Banco VES (CSV)", "maxLength": 100 }, "format": { "type": "string", "example": "csv", "enum": [ "csv", "xlsx" ] }, "columns_by": { "description": "How `columns` name the columns: by spreadsheet letter (the default) or by the title printed in the header row.", "type": "string", "example": "letter", "nullable": true, "enum": [ "letter", "header" ] }, "header_row": { "description": "The 1-based row holding the column titles; 0 when the file has none. At least 1 when `columns_by` is `header`.", "type": "integer", "example": 3, "maximum": 100, "minimum": 0 }, "delimiter": { "description": "Required for csv; absent or null for xlsx.", "type": "string", "example": "semicolon", "nullable": true, "enum": [ "comma", "semicolon", "tab", "pipe" ] }, "date_format": { "description": "Defaults to d/m/Y.", "type": "string", "example": "d/m/Y", "nullable": true, "enum": [ "d/m/Y", "d-m-Y", "d.m.Y", "Y-m-d", "Y/m/d", "m/d/Y", "d/m/y" ] }, "number_format": { "description": "es_VE reads 1.234,56; en reads 1,234.56.", "type": "string", "example": "es_VE", "enum": [ "es_VE", "en" ] }, "amount_mode": { "type": "string", "example": "signed", "enum": [ "signed", "debit_credit" ] }, "columns": { "description": "The column of each field: a spreadsheet letter matching ^[A-Za-z]{1,2}$ when `columns_by` is `letter`, a title of at most 100 characters when it is `header`. Omit a field or send null to leave it unmapped. `amount` is required in signed mode and prohibited otherwise; `debit` and `credit` are required in debit_credit mode and prohibited otherwise; no column may be named twice (titles compare without accents, letter case or extra spaces).", "required": [ "operation_date", "description" ], "properties": { "operation_date": { "type": "string", "example": "A", "maxLength": 100 }, "value_date": { "type": "string", "nullable": true, "maxLength": 100 }, "reference": { "type": "string", "example": "B", "nullable": true, "maxLength": 100 }, "description": { "type": "string", "example": "C", "maxLength": 100 }, "amount": { "type": "string", "example": "D", "nullable": true, "maxLength": 100 }, "debit": { "type": "string", "nullable": true, "maxLength": 100 }, "credit": { "type": "string", "nullable": true, "maxLength": 100 }, "balance": { "type": "string", "example": "E", "nullable": true, "maxLength": 100 } }, "type": "object", "additionalProperties": false } }, "type": "object" } } } }, "responses": { "200": { "description": "Profile updated" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankStatementMessageError" } } } }, "403": { "description": "The user lacks the manage permission, or the API key scope or tenant membership refuses the request", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/BankStatementProblem" }, { "$ref": "#/components/schemas/BankStatementMiddlewareProblem" } ] } } } }, "404": { "description": "The profile does not exist in this company (bank_statement_import_profile_not_found), or the tenant is unknown", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/BankStatementProblem" }, { "$ref": "#/components/schemas/BankStatementMessageError" } ] } } } }, "409": { "description": "Another profile of the company has the name: bank_statement_import_profile_name_already_exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankStatementProblem" } } } }, "422": { "description": "Validation error (`errors` names the fields, the id included), or, as a backstop, a domain refusal: invalid_bank_statement_import_profile_name, invalid_bank_statement_file_format, invalid_bank_statement_columns_by, invalid_bank_statement_header_row, bank_statement_import_profile_header_row_required, invalid_bank_statement_delimiter, bank_statement_import_profile_delimiter_mismatch, invalid_bank_statement_date_format, invalid_bank_statement_number_format, invalid_bank_statement_amount_mode, invalid_bank_statement_column, invalid_bank_statement_column_header, bank_statement_import_profile_operation_date_column_missing, bank_statement_import_profile_description_column_missing, bank_statement_import_profile_amount_columns_invalid, bank_statement_import_profile_columns_overlap", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankStatementProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Backoffice - Treasury - Bank Statement Import Profiles" ], "summary": "Delete a bank statement import profile", "description": "Always allowed: an import keeps the name of the profile it was read with. Requires `backoffice.treasury.bank-reconciliations.manage`.", "operationId": "deleteBankStatementImportProfile", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "The profile id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Profile deleted" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankStatementMessageError" } } } }, "403": { "description": "The user lacks the manage permission, or the API key scope or tenant membership refuses the request", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/BankStatementProblem" }, { "$ref": "#/components/schemas/BankStatementMiddlewareProblem" } ] } } } }, "404": { "description": "The profile does not exist in this company (bank_statement_import_profile_not_found), or the tenant is unknown", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/BankStatementProblem" }, { "$ref": "#/components/schemas/BankStatementMessageError" } ] } } } }, "422": { "description": "The id is not a UUID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankStatementProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/treasury/bank-statement-import-profiles": { "get": { "tags": [ "Backoffice - Treasury - Bank Statement Import Profiles" ], "summary": "Search the bank statement import profiles", "description": "Lists the company's bank statement import profiles ordered by name. A company without profiles returns an empty `items` list with `total` 0. Requires `backoffice.treasury.bank-reconciliations.view`.", "operationId": "searchBankStatementImportProfiles", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "search", "in": "query", "description": "Partial match on the name", "required": false, "schema": { "type": "string", "maxLength": 100 } }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "csv", "xlsx" ] } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "A page of profiles", "content": { "application/json": { "schema": { "required": [ "items", "total", "per_page", "current_page" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/BankStatementImportProfileResource" } }, "total": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 20 }, "current_page": { "type": "integer", "example": 1 } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankStatementMessageError" } } } }, "403": { "description": "The user lacks the view permission, or the API key scope or tenant membership refuses the request", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/BankStatementProblem" }, { "$ref": "#/components/schemas/BankStatementMiddlewareProblem" } ] } } } }, "404": { "description": "Unknown tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankStatementMessageError" } } } }, "422": { "description": "Invalid filter or pagination parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankStatementProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Treasury - Bank Statement Import Profiles" ], "summary": "Create a bank statement import profile", "description": "Creates a company's column mapping for one bank's CSV or Excel export. Columns are named by spreadsheet letter (A–ZZ) or, with `columns_by: header`, by the title the file prints in its header row, matched without accents, letter case or extra spaces. The operation date and description columns are required; a `signed` profile maps `amount` and neither `debit` nor `credit`, a `debit_credit` profile maps both `debit` and `credit` and not `amount`; no column may hold two fields. A csv profile needs a delimiter and an xlsx profile takes none. The name is unique per company, ignoring letter case. Requires `backoffice.treasury.bank-reconciliations.manage`.", "operationId": "createBankStatementImportProfile", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "id", "name", "format", "header_row", "number_format", "amount_mode", "columns" ], "properties": { "id": { "description": "Client-generated.", "type": "string", "format": "uuid", "example": "0190f9b0-7c3e-7c3e-8c3e-0190f9b07c3e" }, "name": { "type": "string", "example": "Banco VES (CSV)", "maxLength": 100 }, "format": { "type": "string", "example": "csv", "enum": [ "csv", "xlsx" ] }, "columns_by": { "description": "How `columns` name the columns: by spreadsheet letter (the default) or by the title printed in the header row.", "type": "string", "example": "letter", "nullable": true, "enum": [ "letter", "header" ] }, "header_row": { "description": "The 1-based row holding the column titles; 0 when the file has none. At least 1 when `columns_by` is `header`.", "type": "integer", "example": 3, "maximum": 100, "minimum": 0 }, "delimiter": { "description": "Required for csv; absent or null for xlsx.", "type": "string", "example": "semicolon", "nullable": true, "enum": [ "comma", "semicolon", "tab", "pipe" ] }, "date_format": { "description": "Defaults to d/m/Y.", "type": "string", "example": "d/m/Y", "nullable": true, "enum": [ "d/m/Y", "d-m-Y", "d.m.Y", "Y-m-d", "Y/m/d", "m/d/Y", "d/m/y" ] }, "number_format": { "description": "es_VE reads 1.234,56; en reads 1,234.56.", "type": "string", "example": "es_VE", "enum": [ "es_VE", "en" ] }, "amount_mode": { "type": "string", "example": "signed", "enum": [ "signed", "debit_credit" ] }, "columns": { "description": "The column of each field: a spreadsheet letter matching ^[A-Za-z]{1,2}$ when `columns_by` is `letter`, a title of at most 100 characters when it is `header`. Omit a field or send null to leave it unmapped. `amount` is required in signed mode and prohibited otherwise; `debit` and `credit` are required in debit_credit mode and prohibited otherwise; no column may be named twice (titles compare without accents, letter case or extra spaces).", "required": [ "operation_date", "description" ], "properties": { "operation_date": { "type": "string", "example": "A", "maxLength": 100 }, "value_date": { "type": "string", "nullable": true, "maxLength": 100 }, "reference": { "type": "string", "example": "B", "nullable": true, "maxLength": 100 }, "description": { "type": "string", "example": "C", "maxLength": 100 }, "amount": { "type": "string", "example": "D", "nullable": true, "maxLength": 100 }, "debit": { "type": "string", "nullable": true, "maxLength": 100 }, "credit": { "type": "string", "nullable": true, "maxLength": 100 }, "balance": { "type": "string", "example": "E", "nullable": true, "maxLength": 100 } }, "type": "object", "additionalProperties": false } }, "type": "object" } } } }, "responses": { "201": { "description": "Profile created" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankStatementMessageError" } } } }, "403": { "description": "The user lacks the manage permission, or the API key scope or tenant membership refuses the request", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/BankStatementProblem" }, { "$ref": "#/components/schemas/BankStatementMiddlewareProblem" } ] } } } }, "404": { "description": "Unknown tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankStatementMessageError" } } } }, "409": { "description": "The id or the name already exists: bank_statement_import_profile_already_exists, bank_statement_import_profile_name_already_exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankStatementProblem" } } } }, "422": { "description": "Validation error (`errors` names the fields), or, as a backstop, a domain refusal: invalid_bank_statement_import_profile_name, invalid_bank_statement_file_format, invalid_bank_statement_columns_by, invalid_bank_statement_header_row, bank_statement_import_profile_header_row_required, invalid_bank_statement_delimiter, bank_statement_import_profile_delimiter_mismatch, invalid_bank_statement_date_format, invalid_bank_statement_number_format, invalid_bank_statement_amount_mode, invalid_bank_statement_column, invalid_bank_statement_column_header, bank_statement_import_profile_operation_date_column_missing, bank_statement_import_profile_description_column_missing, bank_statement_import_profile_amount_columns_invalid, bank_statement_import_profile_columns_overlap", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankStatementProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/treasury/bank-statement-imports/{id}/confirm": { "post": { "tags": [ "Backoffice - Treasury - Bank Statement Imports" ], "summary": "Confirm a draft bank statement import", "description": "Persists the draft's new rows as Bank Statement Lines, never edited afterwards, and raises BankStatementImported. A draft with `error` rows confirms only with `discard_errors: true`, which leaves them out (422 bank_statement_import_has_errors otherwise, persisting nothing). Duplicates are checked again against the account's lines as they stand now, so a row another import brought in since is skipped and counted as a duplicate; with no new row left the draft is refused and stays a draft. Concurrent confirms for one account are serialized. A draft confirms at most once. Requires `backoffice.treasury.bank-reconciliations.manage`.", "operationId": "confirmBankStatementImport", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "The import id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "discard_errors": { "description": "Confirm a draft with error rows, leaving them out. Defaults to false.", "type": "boolean", "example": true } }, "type": "object" } } } }, "responses": { "200": { "description": "The confirmed import", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankStatementImportResource" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankStatementMessageError" } } } }, "403": { "description": "The user lacks the manage permission, or the API key scope or tenant membership refuses the request", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/BankStatementProblem" }, { "$ref": "#/components/schemas/BankStatementMiddlewareProblem" } ] } } } }, "404": { "description": "The import (bank_statement_import_not_found) or its treasury account (bank_statement_treasury_account_not_found) does not exist in this company, or the tenant is unknown", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/BankStatementProblem" }, { "$ref": "#/components/schemas/BankStatementMessageError" } ] } } } }, "409": { "description": "The import is not a draft (bank_statement_import_already_confirmed, bank_statement_import_discarded), a concurrent import wrote one of its lines first (bank_statement_line_already_imported), or a row that would be new is dated in a bank reconciliation month closed since the upload (bank_statement_import_month_closed, with frozen_through), whatever discard_errors says; the draft stays a draft and is uploaded again", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/BankStatementProblem" }, { "$ref": "#/components/schemas/BankStatementImportMonthClosedProblem" } ] } } } }, "422": { "description": "Validation error (the id or discard_errors), the draft has error rows and discard_errors is not true (bank_statement_import_has_errors), the account shares its accounting account and currency (treasury_account_not_reconcilable, with conflicting_treasury_accounts), or no new row is left (bank_statement_import_nothing_to_import)", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/BankStatementProblem" }, { "$ref": "#/components/schemas/TreasuryAccountNotReconcilableProblem" } ] } } } }, "500": { "description": "A stored row is corrupt (invalid_bank_statement_amount, invalid_bank_statement_fingerprint, invalid_bank_statement_import_row)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankStatementProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/treasury/bank-statement-imports/{id}": { "get": { "tags": [ "Backoffice - Treasury - Bank Statement Imports" ], "summary": "Get a bank statement import", "description": "The import's summary and the titles above its mapped columns; its rows page at /rows. Requires `backoffice.treasury.bank-reconciliations.view`.", "operationId": "findBankStatementImport", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "The import id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The import", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankStatementImportResource" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankStatementMessageError" } } } }, "403": { "description": "The user lacks the view permission, or the API key scope or tenant membership refuses the request", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/BankStatementProblem" }, { "$ref": "#/components/schemas/BankStatementMiddlewareProblem" } ] } } } }, "404": { "description": "The import does not exist in this company (bank_statement_import_not_found), or the tenant is unknown", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/BankStatementProblem" }, { "$ref": "#/components/schemas/BankStatementMessageError" } ] } } } }, "422": { "description": "The id is not a UUID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankStatementProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Backoffice - Treasury - Bank Statement Imports" ], "summary": "Discard a draft bank statement import", "description": "Discards a draft: its rows and its stored file are deleted, and the import stays listed as `discarded` with its counts. Requires `backoffice.treasury.bank-reconciliations.manage`.", "operationId": "discardBankStatementImport", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "The import id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "The draft is discarded" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankStatementMessageError" } } } }, "403": { "description": "The user lacks the manage permission, or the API key scope or tenant membership refuses the request", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/BankStatementProblem" }, { "$ref": "#/components/schemas/BankStatementMiddlewareProblem" } ] } } } }, "404": { "description": "The import does not exist in this company (bank_statement_import_not_found), or the tenant is unknown", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/BankStatementProblem" }, { "$ref": "#/components/schemas/BankStatementMessageError" } ] } } } }, "409": { "description": "The import is not a draft: bank_statement_import_already_confirmed, bank_statement_import_discarded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankStatementProblem" } } } }, "422": { "description": "The id is not a UUID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankStatementProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/treasury/accounts/{treasuryAccountId}/bank-statement-imports": { "post": { "tags": [ "Backoffice - Treasury - Bank Statement Imports" ], "summary": "Upload a bank statement as a draft import", "description": "Reads a CSV or Excel statement with one of the company's import profiles for the treasury account of the path into a draft: every non-blank data row is flagged `new`, `duplicate` (its Statement Fingerprint is already a line of the account) or `error` (with its code and detail). Nothing becomes a Bank Statement Line until the draft is confirmed. The file is stored as the import's evidence. The account must be reconcilable: no other active treasury account of the company may share its accounting account and currency (422 treasury_account_not_reconcilable, naming them). A profile that finds its columns by title refuses a file whose header row lacks one (422 bank_statement_header_not_found, naming the missing titles). A csv profile reads `.csv` and `.txt` files, an xlsx profile `.xlsx` files. At most 10 MB and 5,000 data rows. Requires `backoffice.treasury.bank-reconciliations.manage`.", "operationId": "uploadBankStatementImport", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "treasuryAccountId", "in": "path", "description": "The treasury account the statement belongs to", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "id", "profile_id", "file" ], "properties": { "id": { "description": "Client-generated id of the import.", "type": "string", "format": "uuid" }, "profile_id": { "type": "string", "format": "uuid" }, "file": { "description": "The statement: csv, txt or xlsx, both by MIME type and by extension, at most 10240 KB.", "type": "string", "format": "binary" } }, "type": "object" } } } }, "responses": { "201": { "description": "The draft import", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankStatementImportResource" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankStatementMessageError" } } } }, "403": { "description": "The user lacks the manage permission, or the API key scope or tenant membership refuses the request", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/BankStatementProblem" }, { "$ref": "#/components/schemas/BankStatementMiddlewareProblem" } ] } } } }, "404": { "description": "The treasury account (bank_statement_treasury_account_not_found) or the profile (bank_statement_import_profile_not_found) does not exist in this company, or the tenant is unknown", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/BankStatementProblem" }, { "$ref": "#/components/schemas/BankStatementMessageError" } ] } } } }, "409": { "description": "The id already exists: bank_statement_import_already_exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankStatementProblem" } } } }, "422": { "description": "Validation error (the account id of the path included), or the file or the account was refused: treasury_account_not_reconcilable (with conflicting_treasury_accounts), bank_statement_file_format_mismatch, bank_statement_file_unreadable, bank_statement_file_empty, bank_statement_file_too_many_rows, bank_statement_header_not_found (with missing_headers)", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/BankStatementProblem" }, { "$ref": "#/components/schemas/TreasuryAccountNotReconcilableProblem" }, { "$ref": "#/components/schemas/BankStatementHeaderNotFoundProblem" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/treasury/bank-statement-imports/{id}/rows": { "get": { "tags": [ "Backoffice - Treasury - Bank Statement Imports" ], "summary": "Search the rows of a bank statement import", "description": "The import's rows in file order, as read with its profile, each with the cells the bank wrote. A discarded import has none. Requires `backoffice.treasury.bank-reconciliations.view`.", "operationId": "searchBankStatementImportRows", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "The import id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "new", "duplicate", "error" ] } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "maximum": 200, "minimum": 1 } } ], "responses": { "200": { "description": "A page of rows", "content": { "application/json": { "schema": { "required": [ "items", "total", "per_page", "current_page" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/BankStatementImportRowResource" } }, "total": { "type": "integer", "example": 13 }, "per_page": { "type": "integer", "example": 50 }, "current_page": { "type": "integer", "example": 1 } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankStatementMessageError" } } } }, "403": { "description": "The user lacks the view permission, or the API key scope or tenant membership refuses the request", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/BankStatementProblem" }, { "$ref": "#/components/schemas/BankStatementMiddlewareProblem" } ] } } } }, "404": { "description": "The import does not exist in this company (bank_statement_import_not_found), or the tenant is unknown", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/BankStatementProblem" }, { "$ref": "#/components/schemas/BankStatementMessageError" } ] } } } }, "422": { "description": "The id is not a UUID, or an invalid filter or pagination parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankStatementProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/treasury/bank-statement-imports": { "get": { "tags": [ "Backoffice - Treasury - Bank Statement Imports" ], "summary": "Search the bank statement imports", "description": "Lists the company's statement imports, newest upload first. Requires `backoffice.treasury.bank-reconciliations.view`.", "operationId": "searchBankStatementImports", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "treasury_account_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "draft", "confirmed", "discarded" ] } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "A page of imports", "content": { "application/json": { "schema": { "required": [ "items", "total", "per_page", "current_page" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/BankStatementImportResource" } }, "total": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 20 }, "current_page": { "type": "integer", "example": 1 } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankStatementMessageError" } } } }, "403": { "description": "The user lacks the view permission, or the API key scope or tenant membership refuses the request", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/BankStatementProblem" }, { "$ref": "#/components/schemas/BankStatementMiddlewareProblem" } ] } } } }, "404": { "description": "Unknown tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankStatementMessageError" } } } }, "422": { "description": "Invalid filter or pagination parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankStatementProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/treasury/bank-statement-lines/{id}/note": { "put": { "tags": [ "Backoffice - Treasury - Bank Statement Lines" ], "summary": "Write or clear the note of a bank statement line", "description": "Replaces the note of a Bank Statement Line, such as an unidentified credit, keeping who wrote it and when; `null`, an empty or a blank note clears it with its stamp. Writing the note the line already carries keeps its first author and time. The movement is never edited and the note never changes the line's match state. Requires `backoffice.treasury.bank-reconciliations.manage`.", "operationId": "updateBankStatementLineNote", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "The bank statement line", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "note" ], "properties": { "note": { "description": "Trimmed; null, empty or blank clears the note.", "type": "string", "example": "Depósito sin identificar", "nullable": true, "maxLength": 500 } }, "type": "object" } } } }, "responses": { "200": { "description": "The line with its note", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankStatementLineResource" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankStatementMessageError" } } } }, "403": { "description": "The user lacks the manage permission, the API key cannot write, or the tenant membership refuses the request", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/BankStatementProblem" }, { "$ref": "#/components/schemas/BankStatementMiddlewareProblem" } ] } } } }, "404": { "description": "The line does not exist in this company (bank_statement_line_not_found), or the tenant is unknown", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/BankStatementProblem" }, { "$ref": "#/components/schemas/BankStatementMessageError" } ] } } } }, "422": { "description": "Validation error (the id is not a UUID; the note is missing, not a string or longer than 500 characters), or the note is not 1 to 500 characters once trimmed (bank_statement_line_note_invalid)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankStatementProblem" } } } }, "500": { "description": "The stored note has no time it was written (invalid_bank_statement_line_note)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankStatementProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/treasury/accounts/{treasuryAccountId}/bank-statement-lines": { "get": { "tags": [ "Backoffice - Treasury - Bank Statement Lines" ], "summary": "Search the bank statement lines of a treasury account", "description": "Lists the Bank Statement Lines of the treasury account of the path by operation day, then creation, then file row; both bounds of the day range are included. Requires `backoffice.treasury.bank-reconciliations.view`.", "operationId": "searchBankStatementLines", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "treasuryAccountId", "in": "path", "description": "The treasury account", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "description": "The first operation day, Y-m-d.", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "description": "The last operation day, Y-m-d; on or after `from` when both are given.", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "maximum": 200, "minimum": 1 } } ], "responses": { "200": { "description": "A page of lines", "content": { "application/json": { "schema": { "required": [ "items", "total", "per_page", "current_page" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/BankStatementLineResource" } }, "total": { "type": "integer", "example": 13 }, "per_page": { "type": "integer", "example": 50 }, "current_page": { "type": "integer", "example": 1 } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankStatementMessageError" } } } }, "403": { "description": "The user lacks the view permission, or the API key scope or tenant membership refuses the request", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/BankStatementProblem" }, { "$ref": "#/components/schemas/BankStatementMiddlewareProblem" } ] } } } }, "404": { "description": "The treasury account does not exist in this company (bank_statement_treasury_account_not_found), or the tenant is unknown", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/BankStatementProblem" }, { "$ref": "#/components/schemas/BankStatementMessageError" } ] } } } }, "422": { "description": "The account id is not a UUID, a malformed date, a range that ends before it starts, or an invalid pagination parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankStatementProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/treasury/cash-registers/{id}/movement-counterparts": { "get": { "tags": [ "Backoffice - Treasury - Cash Movements" ], "summary": "List a Caja's movement counterparts", "description": "The counterparts a Movimiento de caja of the Caja may use (MER-5151): a narrow read on the POS surface (ADR 0321), exactly the accounts a POST cash-shifts/{id}/movements accepts as its counterpart_treasury_account_id, because both ask the same domain rule. Each carries its id, name, kind and currency only. Sorted by name, then currency. A Caja with no qualifying account answers an empty list; an unknown Caja and another company's answer the same 404 cash_register_not_found. Requires backoffice.treasury.cash-shifts.operate; a POS session token reaches it. A plain read with no lock.", "operationId": "9c5e84762f51cbc63fc6ea72eafbd938", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "The Caja whose counterparts to list.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The counterparts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CashMovementCounterpartList" } } } }, "401": { "description": "Unauthenticated: the auth middleware answers before the controller", "content": { "application/json": { "schema": { "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "403": { "description": "Without backoffice.treasury.cash-shifts.operate (the Problem body, from the route's permission gate), or a caller who does not belong to the company (the tenant middleware's body, which carries a reason when the user has no role there)", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/CashMovementCounterpartProblem" }, { "required": [ "title", "status", "detail" ], "properties": { "title": { "type": "string", "example": "Forbidden" }, "status": { "type": "integer", "example": 403 }, "detail": { "type": "string", "example": "You do not have access to this tenant" }, "reason": { "type": "string" } }, "type": "object" } ] } } } }, "404": { "description": "cash_register_not_found: no such Caja in the company, the same answer for another company's; or the middleware's answer for a tenant the caller or the POS token does not reach", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CashMovementCounterpartProblem" }, { "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Recurso no encontrado" } }, "type": "object" } ] } } } }, "422": { "description": "id is not a UUID (errors names it)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CashMovementCounterpartProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/treasury/cash-shifts/{id}/movements": { "get": { "tags": [ "Backoffice - Treasury - Cash Movements" ], "summary": "List cash movements of a shift", "description": "Returns every Movimiento de caja attributed to the Turno, each with its Treasury Transfer summary. Requires `backoffice.treasury.cash-shifts.view`.", "operationId": "373197ee8eb7afc031b6d0040ab0092e", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "Cash shift id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Cash movements of the shift", "content": { "application/json": { "schema": { "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "required": [ "id", "kind", "counterpart_treasury_account_id", "currency", "amount", "reason", "treasury_transfer_id", "transfer" ], "properties": { "id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "deposit", "withdrawal" ] }, "counterpart_treasury_account_id": { "type": "string", "format": "uuid" }, "currency": { "type": "string" }, "amount": { "type": "string" }, "reason": { "type": "string" }, "treasury_transfer_id": { "type": "string", "format": "uuid" }, "transfer": { "type": "object" } }, "type": "object" } } }, "type": "object" } } } }, "403": { "description": "The user lacks the view permission" }, "404": { "description": "cash_shift_not_found" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Treasury - Cash Movements" ], "summary": "Record a cash movement on an open shift", "description": "Records a deposit or withdrawal on an open Turno as a same-currency Treasury Transfer. The client `id` is both the movement id and the transfer id: resending it with the same terms answers 200; with other terms 409 `cash_movement_id_conflict`. Withdrawal moves register→counterpart; deposit moves counterpart→register. Requires `backoffice.treasury.cash-shifts.operate`.", "operationId": "5616537b3971c739b408a73e83698a6b", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "Cash shift id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "id", "kind", "counterpart_treasury_account_id", "amount", "reason" ], "properties": { "id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "deposit", "withdrawal" ] }, "counterpart_treasury_account_id": { "type": "string", "format": "uuid" }, "amount": { "type": "string", "pattern": "^(?!0+\\\\.0{2}$)\\\\d+\\\\.\\\\d{2}$", "example": "10.00" }, "reason": { "type": "string", "pattern": ".*\\\\S.*", "example": "Retiro a banco", "maxLength": 500, "minLength": 1 } }, "type": "object" } } } }, "responses": { "201": { "description": "Cash movement recorded" }, "200": { "description": "Idempotent replay of the same id and terms" }, "403": { "description": "The user lacks the operate permission" }, "404": { "description": "cash_shift_not_found" }, "409": { "description": "cash_shift_not_open or cash_movement_id_conflict" }, "422": { "description": "cash_movement_counterpart_invalid, invalid_cash_movement_reason, invalid_cash_movement_amount, or a transfer domain refusal" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/treasury/cash-registers/{id}/activate": { "post": { "tags": [ "Backoffice - Treasury - Cash Registers" ], "summary": "Activate a cash register", "description": "Activates an inactive cash register. Requires `backoffice.treasury.cash-registers.manage`.", "operationId": "20b470b3bb9f5584c95b33c2580c00f4", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Cash register activated" }, "403": { "description": "The user lacks the manage permission" }, "404": { "description": "cash_register_not_found" }, "409": { "description": "cash_register_status_transition_not_allowed" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/treasury/cash-registers/{id}/deactivate": { "post": { "tags": [ "Backoffice - Treasury - Cash Registers" ], "summary": "Deactivate a cash register", "description": "Deactivates an active cash register. Refuses with 409 cash_register_has_open_shift when a shift is open. Requires `backoffice.treasury.cash-registers.manage`.", "operationId": "5371c0e13be56cd79ce7e4caf21592d2", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Cash register deactivated" }, "403": { "description": "The user lacks the manage permission" }, "404": { "description": "cash_register_not_found" }, "409": { "description": "cash_register_status_transition_not_allowed or cash_register_has_open_shift" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/treasury/cash-registers/{id}": { "get": { "tags": [ "Backoffice - Treasury - Cash Registers" ], "summary": "Get a cash register", "description": "Requires `backoffice.treasury.cash-registers.view`.", "operationId": "47ae384e632a66f6f998b3d04f019d36", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The cash register" }, "403": { "description": "The user lacks the view permission" }, "404": { "description": "cash_register_not_found" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Backoffice - Treasury - Cash Registers" ], "summary": "Update a cash register", "description": "Replaces the cash register name, optional sales channel and exclusive cash accounts. Requires `backoffice.treasury.cash-registers.manage`.", "operationId": "0593b00e6a18f362c7ff553eb57825d0", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "accounts" ], "properties": { "name": { "type": "string", "maxLength": 100 }, "sales_channel_id": { "type": "string", "format": "uuid", "nullable": true }, "accounts": { "type": "array", "items": { "required": [ "currency", "treasury_account_id" ], "properties": { "currency": { "type": "string", "enum": [ "USD", "VES", "USDT", "EUR", "DOP" ] }, "treasury_account_id": { "type": "string", "format": "uuid" } }, "type": "object" } } }, "type": "object" } } } }, "responses": { "200": { "description": "Cash register updated" }, "403": { "description": "The user lacks the manage permission" }, "404": { "description": "cash_register_not_found or cash_register_account_not_found" }, "422": { "description": "Validation or assignment refusal" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/treasury/cash-registers": { "get": { "tags": [ "Backoffice - Treasury - Cash Registers" ], "summary": "Search cash registers", "description": "Lists the company's cash registers. Requires `backoffice.treasury.cash-registers.view`.", "operationId": "b19955c1e044279a673b73bd015f642e", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "active", "inactive" ] } }, { "name": "status[]", "in": "query", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "active", "inactive" ] }, "maxItems": 2 } }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 100 } }, { "name": "sort_by", "in": "query", "required": false, "schema": { "type": "string", "default": "name", "enum": [ "name", "code", "status", "created_at" ] } }, { "name": "sort_order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "group_by", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "status" ] } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "A page of cash registers" }, "403": { "description": "The user lacks the view permission" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Treasury - Cash Registers" ], "summary": "Create a cash register", "description": "Creates an active cash register with exclusive cash treasury accounts per currency (MER-4172). Each account must be an active cash treasury account of this company, alone on its ledger position, and owned by no other register. `sales_channel_id` is stored as-is without existence checks. Requires `backoffice.treasury.cash-registers.manage`.", "operationId": "6ffb43b03e25fc70d465b727d4bce3a1", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "id", "code", "name", "accounts" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "description": "After trimming, 2 to 40 uppercase letters, digits, hyphens or underscores. Unique per company.", "type": "string", "example": "CAJA-01" }, "name": { "type": "string", "example": "Caja principal", "maxLength": 100 }, "sales_channel_id": { "type": "string", "format": "uuid", "nullable": true }, "accounts": { "type": "array", "items": { "required": [ "currency", "treasury_account_id" ], "properties": { "currency": { "type": "string", "enum": [ "USD", "VES", "USDT", "EUR", "DOP" ] }, "treasury_account_id": { "type": "string", "format": "uuid" } }, "type": "object" } } }, "type": "object" } } } }, "responses": { "201": { "description": "Cash register created" }, "403": { "description": "The user lacks the manage permission" }, "404": { "description": "A treasury account does not exist: cash_register_account_not_found" }, "409": { "description": "The id or code already exists: cash_register_already_exists, cash_register_code_already_exists" }, "422": { "description": "Validation or assignment refusal: invalid_cash_register_code, invalid_cash_register_name, cash_register_account_not_cash, cash_register_account_inactive, cash_register_account_currency_mismatch, cash_register_account_position_shared, cash_register_account_taken, cash_register_account_currency_duplicate", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string" }, "error_code": { "type": "string", "example": "cash_register_account_position_shared", "nullable": true }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/treasury/cash-counts/{id}/post-differences": { "post": { "tags": [ "Backoffice - Treasury - Cash Shifts" ], "summary": "Post cash-count differences", "description": "Posts, once, the per-currency physical-rail differences of a closed arqueo as a single ledger entry (or marks reviewed when all differences are zero). Requires `backoffice.treasury.cash-counts.supervise`.", "operationId": "fab67b2141fa852dff962ab7586a9817", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "Cash count id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Differences posted or reviewed with zero diffs", "content": { "application/json": { "schema": { "required": [ "status", "transaction_id", "differences_posted_at", "differences_posted_by" ], "properties": { "status": { "type": "string", "enum": [ "posted", "reviewed" ] }, "transaction_id": { "type": "string", "format": "uuid", "nullable": true }, "differences_posted_at": { "type": "string", "format": "date-time" }, "differences_posted_by": { "type": "string", "format": "uuid" } }, "type": "object" } } } }, "403": { "description": "The user lacks the supervise permission (Laravel middleware envelope)", "content": { "application/json": { "schema": { "required": [ "message" ], "properties": { "message": { "type": "string" } }, "type": "object" } } } }, "404": { "description": "cash_count_not_found" }, "409": { "description": "cash_count_differences_already_posted, cash_count_earlier_pending, or cash_count_posting_order_ambiguous for indistinguishable legacy timestamps (detail names the earlier count number)" }, "422": { "description": "posting_account_role_missing, closed accounting period, rate snapshot gap, or FormRequest validation", "content": { "application/json": { "schema": { "oneOf": [ { "required": [ "title", "status", "detail" ], "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string" }, "error_code": { "type": "string", "example": "posting_account_role_missing", "nullable": true } }, "type": "object" }, { "required": [ "message" ], "properties": { "message": { "type": "string" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/treasury/cash-counts/{id}": { "get": { "tags": [ "Backoffice - Treasury - Cash Shifts" ], "summary": "Get an immutable cash count", "description": "Returns the closed arqueo exactly as stored, including frozen methods[] (instrument name/class and applied/cancelled totals, MER-4175) and, per line, the frozen breakdown of its expected cash (MER-5688). Requires `backoffice.treasury.cash-shifts.view`.", "operationId": "9961020188f08f55e0defd2869f01bbf", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The cash count with frozen methods[] and optional differences posting stamp (MER-4169)", "content": { "application/json": { "schema": { "required": [ "id", "company_id", "cash_register_id", "cash_shift_id", "number", "closed_by", "closed_at", "lines", "methods", "differences_posted_at", "differences_posted_by", "differences_posted_transaction_id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "cash_register_id": { "type": "string", "format": "uuid" }, "cash_shift_id": { "type": "string", "format": "uuid" }, "number": { "type": "integer" }, "closed_by": { "type": "string", "format": "uuid" }, "closed_at": { "type": "string", "format": "date-time" }, "lines": { "type": "array", "items": { "required": [ "currency", "counted_amount", "expected_amount", "difference_amount", "expected_breakdown" ], "properties": { "currency": { "type": "string" }, "counted_amount": { "type": "string" }, "expected_amount": { "type": "string" }, "difference_amount": { "type": "string" }, "expected_breakdown": { "description": "Frozen at the close. Null on an arqueo closed before it was stored, and on a Turno that opened before it had a ledger cut.", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/CashCountExpectedBreakdown" } ] } }, "type": "object" } }, "methods": { "type": "array", "items": { "required": [ "instrument_id", "instrument_name", "instrument_class", "currency", "applied_amount", "cancelled_amount" ], "properties": { "instrument_id": { "type": "string", "format": "uuid" }, "instrument_name": { "type": "string" }, "instrument_class": { "type": "string" }, "currency": { "type": "string" }, "applied_amount": { "type": "string" }, "cancelled_amount": { "type": "string" } }, "type": "object" } }, "differences_posted_at": { "type": "string", "format": "date-time", "nullable": true }, "differences_posted_by": { "type": "string", "format": "uuid", "nullable": true }, "differences_posted_transaction_id": { "type": "string", "format": "uuid", "nullable": true }, "posting_plan": { "required": [ "earlier_pending_number", "lines", "deductions" ], "properties": { "earlier_pending_number": { "type": "integer", "nullable": true }, "lines": { "type": "array", "items": { "required": [ "currency", "counted_amount", "expected_amount", "difference_amount", "expected_breakdown" ], "properties": { "currency": { "type": "string" }, "counted_amount": { "type": "string" }, "expected_amount": { "type": "string" }, "difference_amount": { "type": "string" }, "expected_breakdown": { "description": "The breakdown of the line this plan posts, as the arqueo froze it.", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/CashCountExpectedBreakdown" } ] } }, "type": "object" } }, "deductions": { "type": "array", "items": { "required": [ "number", "currency", "difference_amount" ], "properties": { "number": { "type": "integer" }, "currency": { "type": "string" }, "difference_amount": { "type": "string" } }, "type": "object" } } }, "type": "object", "nullable": true } }, "type": "object" } } } }, "403": { "description": "The user lacks the view permission (Laravel middleware envelope)", "content": { "application/json": { "schema": { "required": [ "message" ], "properties": { "message": { "type": "string" } }, "type": "object" } } } }, "404": { "description": "cash_count_not_found" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/treasury/cash-registers/{id}/cash-counts": { "get": { "tags": [ "Backoffice - Treasury - Cash Shifts" ], "summary": "List cash counts of a register", "description": "Lists immutable arqueos for a cash register, newest number first. Each line carries `expected_breakdown`, a CashCountExpectedBreakdown frozen at the close, or null on an arqueo that froze none (MER-5688). Requires `backoffice.treasury.cash-shifts.view`.", "operationId": "ffce97585673531fdc34fac4ef7eddba", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "Cash register id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "Paginated cash counts" }, "403": { "description": "The user lacks the view permission" }, "404": { "description": "cash_register_not_found" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/treasury/cash-shifts/{id}/close": { "post": { "tags": [ "Backoffice - Treasury - Cash Shifts" ], "summary": "Close a cash shift with an immutable cash count", "description": "Locks the open shift, reads locked ledger positions, assigns a gapless count number, stores the immutable arqueo, and closes the shift. Requires `backoffice.treasury.cash-shifts.operate`.", "operationId": "4b52c9ff02fb3d55553f5d537e1a4a67", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "Cash shift id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "counts" ], "properties": { "counts": { "type": "array", "items": { "required": [ "currency", "counted_amount" ], "properties": { "currency": { "type": "string", "enum": [ "USD", "VES", "USDT", "EUR", "DOP" ] }, "counted_amount": { "type": "string", "example": "95.00" } }, "type": "object" } } }, "type": "object" } } } }, "responses": { "201": { "description": "Cash shift closed; cash count created", "content": { "application/json": { "schema": { "properties": { "cash_count_id": { "type": "string", "format": "uuid" }, "number": { "type": "integer", "example": 1 } }, "type": "object" } } } }, "403": { "description": "The user lacks the operate permission" }, "404": { "description": "cash_shift_not_found" }, "409": { "description": "cash_shift_not_open" }, "422": { "description": "cash_shift_closing_count_incomplete or invalid_cash_count_amount" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/treasury/cash-shifts/{id}": { "get": { "tags": [ "Backoffice - Treasury - Cash Shifts" ], "summary": "Get a cash shift", "description": "Returns the shift with opening lines and live expected cash per currency. While open, also returns live methods[] (applied and cancelled totals by instrument and currency, MER-4175), and on each current_expected[] entry `breakdown`, a CashCountExpectedBreakdown of that reading (MER-5688), null with no ledger cut. Closed shifts return methods as [] and breakdown as null: what the close froze lives on the arqueo. Requires `backoffice.treasury.cash-shifts.view`.", "operationId": "a132e79fd3b454802b42e05c7a2cb135", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The cash shift, including methods[] (live when open, empty when closed) and current_expected[].breakdown (live when open, null when closed)" }, "403": { "description": "The user lacks the view permission" }, "404": { "description": "cash_shift_not_found" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/treasury/cash-registers/{id}/shifts": { "post": { "tags": [ "Backoffice - Treasury - Cash Shifts" ], "summary": "Open a cash shift", "description": "Opens a shift on an active cash register with a counted amount per register currency. Expected cash is the ledger position of each exclusive cash account (ADR 0287). Requires `backoffice.treasury.cash-shifts.operate`.", "operationId": "cfb92168ae6b5757627d3053c55adc65", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "Cash register id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "id", "counts" ], "properties": { "id": { "type": "string", "format": "uuid" }, "responsible_user_id": { "type": "string", "format": "uuid", "nullable": true }, "counts": { "type": "array", "items": { "required": [ "currency", "counted_amount" ], "properties": { "currency": { "type": "string", "enum": [ "USD", "VES", "USDT", "EUR", "DOP" ] }, "counted_amount": { "type": "string", "example": "1000.00" } }, "type": "object" } } }, "type": "object" } } } }, "responses": { "201": { "description": "Cash shift opened" }, "403": { "description": "The user lacks the operate permission" }, "404": { "description": "cash_register_not_found" }, "409": { "description": "cash_shift_already_open or cash_register_inactive" }, "422": { "description": "cash_shift_opening_count_incomplete or invalid_cash_count_amount" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/treasury/cash-registers/{id}/shifts/current": { "get": { "tags": [ "Backoffice - Treasury - Cash Shifts" ], "summary": "Get the current open cash shift of a register", "description": "Returns the open shift with opening lines, live expected cash per currency with its `breakdown`, a CashCountExpectedBreakdown or null with no ledger cut (MER-5688), and live methods[] (applied/cancelled by instrument, MER-4175). Requires `backoffice.treasury.cash-shifts.view`.", "operationId": "0615154f21a4a0800e02a32cb0a991f4", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "Cash register id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "empty", "in": "query", "description": "Set to 204 to return no content when the register has no open shift; otherwise the legacy 404 is returned.", "required": false, "schema": { "type": "string", "enum": [ "204" ] } } ], "responses": { "200": { "description": "The current open cash shift including methods[] and current_expected[].breakdown" }, "204": { "description": "The register has no open cash shift and empty=204 was requested" }, "403": { "description": "The user lacks the view permission" }, "404": { "description": "cash_register_not_found, or cash_shift_not_found without empty=204" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/treasury/payment-instruments/lookup": { "get": { "tags": [ "Backoffice - Treasury - Payment Instrument Lookups" ], "summary": "Lookup active payment instruments for tenant forms", "description": "Tenant membership is enough; no module permission is required. Lists only active instruments whose treasury account is active, ordered by name. Served at `/payment-instruments/lookup`, like every other module lookup, instead of a separate `payment-instrument-lookups` resource.", "operationId": "f08cb260405ea11d7fded62a4de3d7fe", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "currency", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "USD", "VES", "USDT", "EUR", "DOP" ] } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 200, "minimum": 1 } } ], "responses": { "200": { "description": "Minimal active payment instrument projection", "content": { "application/json": { "schema": { "required": [ "items", "total", "per_page", "current_page" ], "properties": { "items": { "type": "array", "items": { "required": [ "id", "name", "class", "currency", "treasury_account_name" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "example": "Pago móvil Banesco" }, "class": { "type": "string", "enum": [ "cash", "bank_transfer", "mobile_payment", "point_of_sale", "zelle", "crypto_wallet", "check", "card" ] }, "currency": { "type": "string", "enum": [ "USD", "VES", "USDT", "EUR", "DOP" ] }, "treasury_account_name": { "type": "string", "example": "Banesco VES" } }, "type": "object" } }, "total": { "type": "integer" }, "per_page": { "type": "integer" }, "current_page": { "type": "integer" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Not a member of this tenant" }, "404": { "description": "Tenant not found" }, "422": { "description": "Invalid currency or pagination" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/treasury/payment-instruments/{id}/activation": { "put": { "tags": [ "Backoffice - Treasury - Payment Instruments" ], "summary": "Activate a payment instrument", "description": "An instrument activates only when it is linked to a treasury account that still fits it: active, of this company, in the instrument currency and of a kind the class accepts; and its class must accept its currency (crypto_wallet only USDT, zelle USD, mobile_payment VES): a `MIG-BINANCE-…` instrument kept in the functional currency (ADR 0204) cannot be activated again. Requires `backoffice.treasury.payment-instruments.manage`.", "operationId": "0e011b44b003385712f405e625927b48", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "The payment instrument id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Payment instrument activated" }, "403": { "description": "The user lacks the manage permission" }, "404": { "description": "The payment instrument or its treasury account does not exist in this company: payment_instrument_not_found, payment_instrument_treasury_account_not_found" }, "409": { "description": "The instrument is already active, or a concurrent save hit a uniqueness conflict: payment_instrument_status_transition_not_allowed, payment_instrument_already_exists, payment_instrument_code_already_exists" }, "422": { "description": "The instrument's class refuses its currency, it has no treasury account, or its account no longer fits: instrument_class_currency_mismatch, payment_instrument_without_treasury_account, payment_instrument_treasury_account_inactive, payment_instrument_treasury_account_currency_mismatch, instrument_class_treasury_account_kind_mismatch", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string", "example": "El instrumento de pago <0190f9b0-7c3e-7c3e-8c3e-0190f9b07c3e> no puede estar activo sin una cuenta de tesorería" }, "error_code": { "type": "string", "example": "payment_instrument_without_treasury_account", "nullable": true } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/treasury/payment-instruments/{id}/deactivation": { "put": { "tags": [ "Backoffice - Treasury - Payment Instruments" ], "summary": "Deactivate a payment instrument", "description": "Requires `backoffice.treasury.payment-instruments.manage`.", "operationId": "e9c213f370a2bcac5a4605b24e5497e3", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "The payment instrument id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Payment instrument deactivated" }, "403": { "description": "The user lacks the manage permission" }, "404": { "description": "The payment instrument does not exist: payment_instrument_not_found" }, "409": { "description": "The instrument is already inactive, or a concurrent save hit a uniqueness conflict: payment_instrument_status_transition_not_allowed, payment_instrument_already_exists, payment_instrument_code_already_exists", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "detail": { "type": "string", "example": "El instrumento de pago <0190f9b0-7c3e-7c3e-8c3e-0190f9b07c3e> no puede pasar del estado a " }, "error_code": { "type": "string", "example": "payment_instrument_status_transition_not_allowed" } }, "type": "object" } } } }, "422": { "description": "The id is not a UUID" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/treasury/payment-instruments/{id}": { "get": { "tags": [ "Backoffice - Treasury - Payment Instruments" ], "summary": "Get a payment instrument", "description": "The instrument with the name of its treasury account, whatever that account's status, and when it was created. Every list item has the same fields, in the same order. Requires `backoffice.treasury.payment-instruments.view`.", "operationId": "332514134549d0ec47dc8f3121f1c32c", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "The payment instrument id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The payment instrument", "content": { "application/json": { "schema": { "required": [ "id", "code", "name", "class", "currency", "treasury_account_id", "treasury_account_name", "operates_outside_national_banking", "status", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string", "example": "PAGO-MOVIL-BANESCO" }, "name": { "type": "string", "example": "Pago móvil Banesco" }, "class": { "type": "string", "enum": [ "cash", "bank_transfer", "mobile_payment", "point_of_sale", "zelle", "crypto_wallet", "check", "card" ] }, "currency": { "type": "string", "enum": [ "USD", "VES", "USDT", "EUR", "DOP" ] }, "treasury_account_id": { "type": "string", "format": "uuid", "nullable": true }, "treasury_account_name": { "type": "string", "example": "Banesco VES", "nullable": true }, "operates_outside_national_banking": { "type": "boolean" }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "created_at": { "description": "When the instrument was created, as a UTC instant; null when no creation time is stored.", "type": "string", "format": "date-time", "example": "2026-10-15T14:02:11+00:00", "nullable": true } }, "type": "object" } } } }, "403": { "description": "The user lacks the view permission" }, "404": { "description": "The payment instrument does not exist: payment_instrument_not_found", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "detail": { "type": "string", "example": "El instrumento de pago <0190f9b0-7c3e-7c3e-8c3e-0190f9b07c3e> no existe" }, "error_code": { "type": "string", "example": "payment_instrument_not_found" } }, "type": "object" } } } }, "422": { "description": "The id is not a UUID" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Backoffice - Treasury - Payment Instruments" ], "summary": "Update a payment instrument", "description": "Replaces the name and the «operates outside the national banking system» flag. `code`, `class`, `currency`, `treasury_account_id` and `status` are prohibited here (422 on the field, nothing is written): code, class and currency never change, the treasury account changes through PUT /payment-instruments/{id}/link and the status through the activation and deactivation endpoints. Requires `backoffice.treasury.payment-instruments.manage`.", "operationId": "308ed96af5b900a167f502b42cbfb725", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "The payment instrument id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "operates_outside_national_banking" ], "properties": { "name": { "type": "string", "example": "Pago móvil Banesco", "maxLength": 100 }, "operates_outside_national_banking": { "type": "boolean", "example": false } }, "type": "object" } } } }, "responses": { "200": { "description": "Payment instrument updated" }, "403": { "description": "The user lacks the manage permission" }, "404": { "description": "The payment instrument does not exist: payment_instrument_not_found", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "detail": { "type": "string", "example": "El instrumento de pago <0190f9b0-7c3e-7c3e-8c3e-0190f9b07c3e> no existe" }, "error_code": { "type": "string", "example": "payment_instrument_not_found" } }, "type": "object" } } } }, "409": { "description": "A concurrent save hit a uniqueness conflict: payment_instrument_already_exists, payment_instrument_code_already_exists" }, "422": { "description": "Validation error (including a prohibited field), or invalid_payment_instrument_name", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string", "example": "The given data was invalid." } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Backoffice - Treasury - Payment Instruments" ], "summary": "Delete an unused payment instrument", "description": "Only an instrument no document uses can be deleted; deactivate a used one instead (409 payment_instrument_in_use). Requires `backoffice.treasury.payment-instruments.manage`.", "operationId": "ae9655a61fc63ffea60a075a24025bc1", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "The payment instrument id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Payment instrument deleted" }, "403": { "description": "The user lacks the manage permission" }, "404": { "description": "The payment instrument does not exist: payment_instrument_not_found" }, "409": { "description": "The payment instrument is in use: payment_instrument_in_use", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "detail": { "type": "string", "example": "El instrumento de pago <0190f9b0-7c3e-7c3e-8c3e-0190f9b07c3e> está en uso y no se puede eliminar; desactívalo en su lugar" }, "error_code": { "type": "string", "example": "payment_instrument_in_use" } }, "type": "object" } } } }, "422": { "description": "The id is not a UUID" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/treasury/payment-instruments/{id}/link": { "put": { "tags": [ "Backoffice - Treasury - Payment Instruments" ], "summary": "Link a payment instrument to a treasury account", "description": "The treasury account must be active, belong to this company, share the instrument currency and be of a kind the instrument class accepts. Relinking the current account changes nothing. Requires `backoffice.treasury.payment-instruments.manage`.", "operationId": "ee0f09073aba2c0311b932b6fc28569d", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "The payment instrument id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "treasury_account_id" ], "properties": { "treasury_account_id": { "type": "string", "format": "uuid", "example": "0190f9b0-7c3e-7c3e-8c3e-0190f9b07ca0" } }, "type": "object" } } } }, "responses": { "200": { "description": "Payment instrument linked" }, "403": { "description": "The user lacks the manage permission" }, "404": { "description": "The payment instrument or the treasury account does not exist in this company: payment_instrument_not_found, payment_instrument_treasury_account_not_found" }, "409": { "description": "A concurrent save hit a uniqueness conflict: payment_instrument_already_exists, payment_instrument_code_already_exists" }, "422": { "description": "Validation error, or the treasury account does not fit: payment_instrument_treasury_account_inactive, payment_instrument_treasury_account_currency_mismatch, instrument_class_treasury_account_kind_mismatch", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string", "example": "Un instrumento de pago de clase no se puede vincular a una cuenta de tesorería de tipo " }, "error_code": { "type": "string", "example": "instrument_class_treasury_account_kind_mismatch", "nullable": true } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/treasury/payment-instruments": { "get": { "tags": [ "Backoffice - Treasury - Payment Instruments" ], "summary": "Search the payment instrument catalog", "description": "Lists the company's payment instruments, active and inactive. Every list filter takes one value or several (`class=zelle` or `class[]=zelle&class[]=cash`): values of one filter are alternatives, filters narrow each other, and an empty filter is ignored. `treasury_account_id` matches the treasury account an instrument is linked to, read in any letter case; an instrument without a treasury account matches none. `search` matches the code or the name, literally; it is trimmed of ASCII whitespace and a blank term searches nothing. `sort_by` defaults to `name`; without `sort_by` the order is ascending unless `sort_order` says otherwise, and a `sort_by` sent without `sort_order` reads descending. `class`, `currency` and `status` order by their stored codes, and ties are settled by id, ascending. `group_by=status` lists active instruments before inactive ones, ahead of the requested order and before paging. `meta.counts` counts the matching instruments by status under every filter but `status`, both statuses always present; it does not depend on the page, its size, the order or the grouping. A company without instruments returns an empty `items` list with `total` 0. Requires `backoffice.treasury.payment-instruments.view`.", "operationId": "84e72570c87370aab1da2cbfb6b09ae0", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "description": "One status. Same as one `status[]`.", "required": false, "schema": { "type": "string", "enum": [ "active", "inactive" ] } }, { "name": "status[]", "in": "query", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "active", "inactive" ] }, "maxItems": 2 } }, { "name": "class", "in": "query", "description": "One class. Same as one `class[]`.", "required": false, "schema": { "type": "string", "enum": [ "cash", "bank_transfer", "mobile_payment", "point_of_sale", "zelle", "crypto_wallet", "check", "card" ] } }, { "name": "class[]", "in": "query", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "cash", "bank_transfer", "mobile_payment", "point_of_sale", "zelle", "crypto_wallet", "check", "card" ] }, "maxItems": 8 } }, { "name": "currency", "in": "query", "description": "One currency. Same as one `currency[]`.", "required": false, "schema": { "type": "string", "enum": [ "USD", "VES", "USDT", "EUR", "DOP" ] } }, { "name": "currency[]", "in": "query", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "USD", "VES", "USDT", "EUR", "DOP" ] }, "maxItems": 5 } }, { "name": "treasury_account_id", "in": "query", "description": "One treasury account. Same as one `treasury_account_id[]`.", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "treasury_account_id[]", "in": "query", "description": "The treasury accounts the instruments are linked to; an unlinked instrument matches none.", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 50 } }, { "name": "search", "in": "query", "description": "Matches the code or the name, literally; trimmed, and blank searches nothing.", "required": false, "schema": { "type": "string", "maxLength": 100 } }, { "name": "sort_by", "in": "query", "required": false, "schema": { "type": "string", "default": "name", "enum": [ "name", "code", "class", "currency", "status", "created_at" ] } }, { "name": "sort_order", "in": "query", "description": "Read case-insensitively. Ascending when `sort_by` is omitted; descending when `sort_by` is sent without it.", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "group_by", "in": "query", "description": "Active instruments first, then inactive ones, before the requested order and before paging.", "required": false, "schema": { "type": "string", "enum": [ "status" ] } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "A page of payment instruments with the list's status counts", "content": { "application/json": { "schema": { "required": [ "items", "total", "per_page", "current_page", "meta" ], "properties": { "items": { "description": "Each item has the same fields, in the same order, as the detail.", "type": "array", "items": { "required": [ "id", "code", "name", "class", "currency", "treasury_account_id", "treasury_account_name", "operates_outside_national_banking", "status", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string", "example": "PAGO-MOVIL-BANESCO" }, "name": { "type": "string", "example": "Pago móvil Banesco" }, "class": { "type": "string", "enum": [ "cash", "bank_transfer", "mobile_payment", "point_of_sale", "zelle", "crypto_wallet", "check", "card" ] }, "currency": { "type": "string", "enum": [ "USD", "VES", "USDT", "EUR", "DOP" ] }, "treasury_account_id": { "type": "string", "format": "uuid", "nullable": true }, "treasury_account_name": { "type": "string", "example": "Banesco VES", "nullable": true }, "operates_outside_national_banking": { "type": "boolean" }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "created_at": { "description": "When the instrument was created, as a UTC instant; null when no creation time is stored.", "type": "string", "format": "date-time", "example": "2026-10-15T14:02:11+00:00", "nullable": true } }, "type": "object" } }, "total": { "type": "integer", "example": 7 }, "per_page": { "type": "integer", "example": 20 }, "current_page": { "type": "integer", "example": 1 }, "meta": { "required": [ "counts" ], "properties": { "counts": { "description": "Matching instruments by status, under every filter but `status`.", "required": [ "active", "inactive" ], "properties": { "active": { "type": "integer", "example": 5 }, "inactive": { "type": "integer", "example": 2 } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks the view permission" }, "422": { "description": "Invalid filter, search, sort, grouping or pagination parameter; `errors` names it, `class.0` for the first class of a list", "content": { "application/json": { "schema": { "required": [ "title", "status", "detail", "errors" ], "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string", "example": "The given data was invalid." }, "error_code": { "type": "string", "example": null, "nullable": true }, "errors": { "description": "The offending query parameters, each with its messages.", "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Internal Server Error" }, "status": { "type": "integer", "example": 500 }, "detail": { "type": "string", "example": "An unexpected error occurred while processing your request." } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Treasury - Payment Instruments" ], "summary": "Register a payment instrument", "description": "Registers a payment instrument, always inactive: activate it afterwards with PUT /payment-instruments/{id}/activation. The `MIG-` code prefix is reserved for migrated instruments (422 payment_instrument_code_reserved). mobile_payment requires VES, zelle requires USD and crypto_wallet requires USDT (422 instrument_class_currency_mismatch). When `treasury_account_id` is sent it must be an active treasury account of this company, in the instrument currency and of a kind the class accepts: cash takes cash; bank_transfer, mobile_payment, point_of_sale and check take bank; zelle and crypto_wallet take wallet; card takes bank or credit_card. Requires `backoffice.treasury.payment-instruments.manage`.", "operationId": "6405131d03198f29945050dc08cc4faf", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "id", "code", "name", "class", "currency" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "0190f9b0-7c3e-7c3e-8c3e-0190f9b07c3e" }, "code": { "description": "After trimming, 2 to 40 uppercase letters, digits or hyphens. Unique per company and immutable once registered.", "type": "string", "example": "PAGO-MOVIL-BANESCO" }, "name": { "type": "string", "example": "Pago móvil Banesco", "maxLength": 100 }, "class": { "description": "Immutable once registered.", "type": "string", "example": "mobile_payment", "enum": [ "cash", "bank_transfer", "mobile_payment", "point_of_sale", "zelle", "crypto_wallet", "check", "card" ] }, "currency": { "description": "Immutable once registered.", "type": "string", "example": "VES", "enum": [ "USD", "VES", "USDT", "EUR", "DOP" ] }, "treasury_account_id": { "description": "Optional; the instrument can be linked later with PUT /payment-instruments/{id}/link.", "type": "string", "format": "uuid", "example": "0190f9b0-7c3e-7c3e-8c3e-0190f9b07ca0", "nullable": true }, "operates_outside_national_banking": { "description": "When omitted it defaults from the class: true for cash, zelle and crypto_wallet, false otherwise.", "type": "boolean", "example": false } }, "type": "object" } } } }, "responses": { "201": { "description": "Payment instrument registered, inactive" }, "403": { "description": "The user lacks the manage permission" }, "404": { "description": "The treasury account does not exist in this company: payment_instrument_treasury_account_not_found", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "detail": { "type": "string", "example": "La cuenta de tesorería <0190f9b0-7c3e-7c3e-8c3e-0190f9b07ca0> no existe" }, "error_code": { "type": "string", "example": "payment_instrument_treasury_account_not_found" } }, "type": "object" } } } }, "409": { "description": "The id or the code already exists: payment_instrument_already_exists, payment_instrument_code_already_exists", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "detail": { "type": "string", "example": "Ya existe un instrumento de pago con el código " }, "error_code": { "type": "string", "example": "payment_instrument_code_already_exists" } }, "type": "object" } } } }, "422": { "description": "Validation error, or a domain rule rejected the instrument: invalid_payment_instrument_code, payment_instrument_code_reserved, invalid_payment_instrument_name, invalid_instrument_class, invalid_currency, instrument_class_currency_mismatch, payment_instrument_treasury_account_inactive, payment_instrument_treasury_account_currency_mismatch, instrument_class_treasury_account_kind_mismatch", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string", "example": "Un instrumento de pago de clase no puede operar en " }, "error_code": { "type": "string", "example": "instrument_class_currency_mismatch", "nullable": true } }, "type": "object" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Internal Server Error" }, "status": { "type": "integer", "example": 500 }, "detail": { "type": "string", "example": "An unexpected error occurred while processing your request." } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/treasury/reconciliation-matches/{id}": { "get": { "tags": [ "Backoffice - Treasury - Reconciliation Matches" ], "summary": "Show a reconciliation match", "description": "A Reconciliation Match of the company, active or undone, with its lines grouped by side. Requires `backoffice.treasury.bank-reconciliations.view`.", "operationId": "showReconciliationMatch", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "The match id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReconciliationMatchResource" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankStatementMessageError" } } } }, "403": { "description": "The user lacks the view permission, or the API key scope or tenant membership refuses the request", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/BankStatementProblem" }, { "$ref": "#/components/schemas/BankStatementMiddlewareProblem" } ] } } } }, "404": { "description": "The match does not exist in this company (reconciliation_match_not_found), or the tenant is unknown", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/BankStatementProblem" }, { "$ref": "#/components/schemas/BankStatementMessageError" } ] } } } }, "422": { "description": "The id is not a UUID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankStatementProblem" } } } }, "500": { "description": "The stored match is corrupt (invalid_reconciliation_match)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankStatementProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/treasury/accounts/{treasuryAccountId}/reconciliation-matches": { "post": { "tags": [ "Backoffice - Treasury - Reconciliation Matches" ], "summary": "Match statement lines with ledger lines of a treasury account", "description": "Creates a Reconciliation Match of Bank Statement Lines of the treasury account with ledger lines of its accounting account and currency, many to many, and raises ReconciliationMatched. Both sides must sum exactly; one side may be empty only when the other sums to zero, such as a cancelled collection and its reversal. Every line must belong to the account and be in no other active match. The account must be reconcilable (ADR 0267). Once the account's bank reconciliation has started (ADR 0268), its opening line may be matched with the books' balance before the start (`pre_start_balance: true`), which joins the book side dated the day before the start month; no match may hold lines dated both before and from the start month, nor lie wholly in closed months (a line dated after the closed-through month lets it through). Concurrent matches of one account are serialized. The id is chosen by the client; sending it again answers 409 reconciliation_match_already_exists. Requires `backoffice.treasury.bank-reconciliations.manage`.", "operationId": "createReconciliationMatch", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "treasuryAccountId", "in": "path", "description": "The treasury account", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "id", "statement_line_ids", "ledger_line_ids" ], "properties": { "id": { "description": "The new match's id, chosen by the client.", "type": "string", "format": "uuid" }, "statement_line_ids": { "description": "The Bank Statement Lines to match; may be empty.", "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 500, "uniqueItems": true }, "ledger_line_ids": { "description": "The ledger lines to match; may be empty.", "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 500, "uniqueItems": true }, "pre_start_balance": { "description": "Also match the books' balance before the account's bank reconciliation starts, at its amount now; only with the account's opening line among statement_line_ids. Defaults to false.", "type": "boolean", "example": true, "default": false } }, "type": "object" } } } }, "responses": { "201": { "description": "The match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReconciliationMatchResource" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankStatementMessageError" } } } }, "403": { "description": "The user lacks the manage permission, or the API key scope or tenant membership refuses the request", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/BankStatementProblem" }, { "$ref": "#/components/schemas/BankStatementMiddlewareProblem" } ] } } } }, "404": { "description": "The treasury account does not exist in this company (reconciliation_treasury_account_not_found), or the tenant is unknown", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/BankStatementProblem" }, { "$ref": "#/components/schemas/BankStatementMessageError" } ] } } } }, "409": { "description": "The id is taken (reconciliation_match_already_exists), an active match already holds a line (reconciliation_line_already_matched, with lines), or every line falls in a closed bank reconciliation month (bank_reconciliation_month_closed, with closed_through)", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/BankStatementProblem" }, { "$ref": "#/components/schemas/ReconciliationLineAlreadyMatchedProblem" }, { "$ref": "#/components/schemas/BankReconciliationMonthClosedProblem" } ] } } } }, "422": { "description": "Validation error, the account shares its accounting account and currency (treasury_account_not_reconcilable, with conflicting_treasury_accounts), a line does not belong to the account (reconciliation_lines_not_in_treasury_account, with lines), no line was given (reconciliation_match_has_no_lines), a line is given twice (reconciliation_match_line_repeated), the sides sum differently (reconciliation_match_unbalanced, with currency, statement_total, ledger_total for the book side and difference), the books' balance before the start was asked of an account whose bank reconciliation has not started (bank_reconciliation_not_started, with start_month null) or without its opening line (reconciliation_pre_start_balance_needs_opening_line), or the lines lie on both sides of the start (bank_reconciliation_match_crosses_start, with start_month)", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/BankStatementProblem" }, { "$ref": "#/components/schemas/TreasuryAccountNotReconcilableProblem" }, { "$ref": "#/components/schemas/ReconciliationLinesNotInTreasuryAccountProblem" }, { "$ref": "#/components/schemas/ReconciliationMatchUnbalancedProblem" }, { "$ref": "#/components/schemas/BankReconciliationNotStartedProblem" }, { "$ref": "#/components/schemas/BankReconciliationMatchCrossesStartProblem" } ] } } } }, "500": { "description": "A ledger line moves units with no side (reconciliation_ledger_line_unsided), or a stored match is corrupt (invalid_reconciliation_match)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankStatementProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/treasury/reconciliation-matches/{id}/undo": { "post": { "tags": [ "Backoffice - Treasury - Reconciliation Matches" ], "summary": "Undo a reconciliation match", "description": "Undoes an active Reconciliation Match and raises ReconciliationMatchUndone: the match stays, undone, with who undid it and when, and its lines are in transit again, free for another match. A match whose lines all fall in closed bank reconciliation months is frozen until the month reopens (ADR 0268). Concurrent matches and undos of one account are serialized. Requires `backoffice.treasury.bank-reconciliations.manage`.", "operationId": "undoReconciliationMatch", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "The match id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The undone match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReconciliationMatchResource" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankStatementMessageError" } } } }, "403": { "description": "The user lacks the manage permission, or the API key scope or tenant membership refuses the request", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/BankStatementProblem" }, { "$ref": "#/components/schemas/BankStatementMiddlewareProblem" } ] } } } }, "404": { "description": "The match does not exist in this company (reconciliation_match_not_found), or the tenant is unknown", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/BankStatementProblem" }, { "$ref": "#/components/schemas/BankStatementMessageError" } ] } } } }, "409": { "description": "The match is already undone (reconciliation_match_already_undone), or every line it holds falls in a closed bank reconciliation month (bank_reconciliation_month_closed, with closed_through)", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/BankStatementProblem" }, { "$ref": "#/components/schemas/BankReconciliationMonthClosedProblem" } ] } } } }, "422": { "description": "The id is not a UUID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankStatementProblem" } } } }, "500": { "description": "The stored match is corrupt (invalid_reconciliation_match)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankStatementProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/treasury/accounts/{treasuryAccountId}/reconciliation-workspace/suggestions": { "get": { "tags": [ "Backoffice - Treasury - Reconciliation Matches" ], "summary": "Suggest reconciliation matches for the in-transit lines of a treasury account", "description": "Reconciliation Suggestions over the in-transit lines of the same window as the workspace, with the same limits and refusals: for each in-transit Bank Statement Line, the exact ones (one ledger line of the same signed amount at most 5 days away, at most 5) then the groups (ledger lines of its sign dated from the previous weekday to its day, weekend included, adding up to its amount, at most 3), and apart the ledger pairs of an entry and its reversal that cancel out. A line of such a pair is offered only as that pair; a statement line of zero gets none. Suggestions are computed on every read and never stored; they may overlap, so refetch them after a match or an undo. Accepting one is `POST …/accounts/{treasuryAccountId}/reconciliation-matches` with its `statement_line_ids` and `ledger_line_ids`. Requires `backoffice.treasury.bank-reconciliations.view`.", "operationId": "searchReconciliationSuggestions", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "treasuryAccountId", "in": "path", "description": "The treasury account", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "description": "The first day, Y-m-d, as for the workspace.", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "description": "The last day, Y-m-d, on or after `from`.", "required": true, "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "The suggestions; empty lists when there are none", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReconciliationSuggestionsResource" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankStatementMessageError" } } } }, "403": { "description": "The user lacks the view permission, or the API key scope or tenant membership refuses the request", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/BankStatementProblem" }, { "$ref": "#/components/schemas/BankStatementMiddlewareProblem" } ] } } } }, "404": { "description": "The treasury account does not exist in this company (reconciliation_treasury_account_not_found), or the tenant is unknown", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/BankStatementProblem" }, { "$ref": "#/components/schemas/BankStatementMessageError" } ] } } } }, "422": { "description": "Validation error (the account id, a missing or malformed day, a range that ends before it starts), the account shares its accounting account and currency (treasury_account_not_reconcilable, with conflicting_treasury_accounts), the range spans more than 92 days (reconciliation_workspace_range_too_long, with max_days), or a side holds more than 2,000 lines (reconciliation_workspace_too_many_lines, with side and limit)", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/BankStatementProblem" }, { "$ref": "#/components/schemas/TreasuryAccountNotReconcilableProblem" }, { "$ref": "#/components/schemas/ReconciliationWorkspaceRangeTooLongProblem" }, { "$ref": "#/components/schemas/ReconciliationWorkspaceTooManyLinesProblem" } ] } } } }, "500": { "description": "A ledger line moves units with no side (reconciliation_ledger_line_unsided), or a stored match is corrupt (invalid_reconciliation_match)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankStatementProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/treasury/accounts/{treasuryAccountId}/reconciliation-workspace": { "get": { "tags": [ "Backoffice - Treasury - Reconciliation Matches" ], "summary": "Show the reconciliation workspace of a treasury account", "description": "Both sides of the treasury account between two days, both included: its Bank Statement Lines and its ledger lines (the lines on its accounting account in its currency that move its balance), each `matched` while an active Reconciliation Match holds it and `in_transit` otherwise, the active matches holding them and each side's totals. The range spans at most 92 days and each side at most 2,000 lines, all returned at once so lines can be selected across both sides. The account must be reconcilable (ADR 0267). Requires `backoffice.treasury.bank-reconciliations.view`.", "operationId": "showReconciliationWorkspace", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "treasuryAccountId", "in": "path", "description": "The treasury account", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "description": "The first day, Y-m-d: an operation day on the statement, an entry day in the ledger.", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "description": "The last day, Y-m-d, on or after `from`.", "required": true, "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "The workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReconciliationWorkspaceResource" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankStatementMessageError" } } } }, "403": { "description": "The user lacks the view permission, or the API key scope or tenant membership refuses the request", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/BankStatementProblem" }, { "$ref": "#/components/schemas/BankStatementMiddlewareProblem" } ] } } } }, "404": { "description": "The treasury account does not exist in this company (reconciliation_treasury_account_not_found), or the tenant is unknown", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/BankStatementProblem" }, { "$ref": "#/components/schemas/BankStatementMessageError" } ] } } } }, "422": { "description": "Validation error (the account id, a missing or malformed day, a range that ends before it starts), the account shares its accounting account and currency (treasury_account_not_reconcilable, with conflicting_treasury_accounts), the range spans more than 92 days (reconciliation_workspace_range_too_long, with max_days), or a side holds more than 2,000 lines (reconciliation_workspace_too_many_lines, with side and limit)", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/BankStatementProblem" }, { "$ref": "#/components/schemas/TreasuryAccountNotReconcilableProblem" }, { "$ref": "#/components/schemas/ReconciliationWorkspaceRangeTooLongProblem" }, { "$ref": "#/components/schemas/ReconciliationWorkspaceTooManyLinesProblem" } ] } } } }, "500": { "description": "A ledger line moves units with no side (reconciliation_ledger_line_unsided), or a stored match is corrupt (invalid_reconciliation_match)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankStatementProblem" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/treasury/accounts/lookup": { "get": { "tags": [ "Backoffice - Treasury - Treasury Account Lookups" ], "summary": "Lookup active treasury accounts for tenant forms", "description": "Tenant membership is enough; no module permission is required. Lists only active treasury accounts, ordered by name, optionally narrowed by currency and by kinds (`?kinds[]=bank&kinds[]=credit_card`).", "operationId": "e2f4b49a1e1c7a738bdc3ea1831d3e16", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "currency", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "USD", "VES", "USDT", "EUR", "DOP" ] } }, { "name": "kinds[]", "in": "query", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "bank", "wallet", "cash", "credit_card" ] } } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 200, "minimum": 1 } } ], "responses": { "200": { "description": "Minimal active treasury account projection", "content": { "application/json": { "schema": { "required": [ "items", "total", "per_page", "current_page" ], "properties": { "items": { "type": "array", "items": { "required": [ "id", "name", "kind", "currency" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "example": "Banesco VES" }, "kind": { "type": "string", "enum": [ "bank", "wallet", "cash", "credit_card" ] }, "currency": { "type": "string", "enum": [ "USD", "VES", "USDT", "EUR", "DOP" ] } }, "type": "object" } }, "total": { "type": "integer" }, "per_page": { "type": "integer" }, "current_page": { "type": "integer" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Not a member of this tenant" }, "404": { "description": "Tenant not found" }, "422": { "description": "Invalid currency, kind or pagination" }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/treasury/accounts/{id}/activation": { "put": { "tags": [ "Backoffice - Treasury - Treasury Accounts" ], "summary": "Activate a treasury account", "description": "Requires `backoffice.treasury.treasury-accounts.manage`.", "operationId": "50f1fe38af762412b9dd43f9904a2211", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "The ID of the treasury account to activate", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Treasury account activated successfully" }, "403": { "description": "The user lacks the manage permission" }, "404": { "description": "Treasury account not found", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "detail": { "type": "string", "example": "La cuenta de tesorería <123e4567-e89b-12d3-a456-426655440000> no existe" } }, "type": "object" } } } }, "409": { "description": "The treasury account cannot be activated from its current status (invalid_treasury_account_status), or a concurrent save hit a uniqueness conflict: treasury_account_already_exists, treasury_account_number_already_exists, treasury_account_identifier_already_exists", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "detail": { "type": "string", "example": "El estado de la cuenta de tesorería no es válido" } }, "type": "object" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Internal Server Error" }, "status": { "type": "integer", "example": 500 }, "detail": { "type": "string", "example": "An unexpected error occurred while processing your request." } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/treasury/accounts/{id}/deactivation": { "put": { "tags": [ "Backoffice - Treasury - Treasury Accounts" ], "summary": "Deactivate a treasury account", "description": "Requires `backoffice.treasury.treasury-accounts.manage`.", "operationId": "863bd6a953161b4f1b428f18c6339ec0", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "The ID of the treasury account to deactivate", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Treasury account deactivated successfully" }, "403": { "description": "The user lacks the manage permission" }, "404": { "description": "Treasury account not found", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "detail": { "type": "string", "example": "La cuenta de tesorería <123e4567-e89b-12d3-a456-426655440000> no existe" } }, "type": "object" } } } }, "409": { "description": "The treasury account cannot be deactivated from its current status (invalid_treasury_account_status), or a concurrent save hit a uniqueness conflict: treasury_account_already_exists, treasury_account_number_already_exists, treasury_account_identifier_already_exists", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "detail": { "type": "string", "example": "El estado de la cuenta de tesorería no es válido" } }, "type": "object" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Internal Server Error" }, "status": { "type": "integer", "example": 500 }, "detail": { "type": "string", "example": "An unexpected error occurred while processing your request." } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/treasury/accounts/{id}/default": { "put": { "tags": [ "Backoffice - Treasury - Treasury Accounts" ], "summary": "Mark a treasury account as the default for its kind and currency", "description": "Requires `backoffice.treasury.treasury-accounts.manage`.", "operationId": "e8de1adb10cb69a54b58a2f8caf28eb2", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "The ID of the treasury account to mark as default", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Treasury account marked as default successfully" }, "403": { "description": "The user lacks the manage permission" }, "404": { "description": "Treasury account not found", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "detail": { "type": "string", "example": "La cuenta de tesorería <123e4567-e89b-12d3-a456-426655440000> no existe" } }, "type": "object" } } } }, "409": { "description": "An inactive treasury account cannot be marked as default (invalid_treasury_account_status), or a concurrent save hit a uniqueness conflict: treasury_account_already_exists, treasury_account_number_already_exists, treasury_account_identifier_already_exists", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "detail": { "type": "string", "example": "El estado de la cuenta de tesorería no es válido" } }, "type": "object" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Internal Server Error" }, "status": { "type": "integer", "example": 500 }, "detail": { "type": "string", "example": "An unexpected error occurred while processing your request." } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/treasury/accounts/{id}": { "get": { "tags": [ "Backoffice - Treasury - Treasury Accounts" ], "summary": "Get a treasury account by ID", "description": "The account with the code and name of its accounting account and center and when it was created: the same fields, in the same order, as a list item. Another company's account is not found. Requires `backoffice.treasury.treasury-accounts.view`.", "operationId": "8affe987d4c53d331d95bde30dc0f62e", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "The ID of the treasury account to retrieve", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Treasury account details", "content": { "application/json": { "schema": { "required": [ "id", "kind", "identifier", "bank_name", "name", "account_number", "type", "currency", "accounting_account_id", "accounting_account_code", "accounting_account_name", "accounting_center_id", "accounting_center_code", "accounting_center_name", "is_default", "status", "company_id", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426655440000" }, "kind": { "type": "string", "example": "wallet", "enum": [ "bank", "wallet", "cash", "credit_card" ] }, "identifier": { "description": "Null for kind bank.", "type": "string", "example": "tesoreria@empresa.com", "nullable": true }, "bank_name": { "description": "Null unless kind is bank.", "type": "string", "example": null, "nullable": true }, "name": { "type": "string", "example": "Binance USDT" }, "account_number": { "description": "Null unless kind is bank.", "type": "string", "example": null, "nullable": true }, "type": { "description": "Null unless kind is bank.", "type": "string", "example": null, "nullable": true, "enum": [ "corriente", "ahorro" ] }, "currency": { "type": "string", "example": "USDT", "enum": [ "DOP", "USD", "VES", "USDT", "EUR" ] }, "accounting_account_id": { "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426655440000" }, "accounting_account_code": { "description": "Null when the accounting account cannot be resolved.", "type": "string", "example": "1.1.02.", "nullable": true }, "accounting_account_name": { "description": "Null when the accounting account cannot be resolved.", "type": "string", "example": "Bancos", "nullable": true }, "accounting_center_id": { "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426655440000" }, "accounting_center_code": { "description": "Null when the accounting center cannot be resolved.", "type": "string", "example": "GEN", "nullable": true }, "accounting_center_name": { "description": "Null when the accounting center cannot be resolved.", "type": "string", "example": "General", "nullable": true }, "is_default": { "type": "boolean", "example": false }, "status": { "type": "string", "example": "active", "enum": [ "active", "inactive" ] }, "company_id": { "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426655440000" }, "created_at": { "description": "When the account was created, as a UTC instant; null for an account without a stored creation time.", "type": "string", "format": "date-time", "example": "2026-10-14T16:58:51+00:00", "nullable": true } }, "type": "object" } } } }, "403": { "description": "The user lacks the view permission" }, "404": { "description": "Treasury account not found", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "detail": { "type": "string", "example": "La cuenta de tesorería <123e4567-e89b-12d3-a456-426655440000> no existe" } }, "type": "object" } } } }, "422": { "description": "The id is not a UUID" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Internal Server Error" }, "status": { "type": "integer", "example": 500 }, "detail": { "type": "string", "example": "An unexpected error occurred while processing your request." } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Backoffice - Treasury - Treasury Accounts" ], "summary": "Update a treasury account", "description": "Replaces the editable fields of a treasury account. `kind` is required and must equal the stored kind (422 treasury_account_kind_is_immutable otherwise); the bank fields and identifier follow the same per-kind rules as creation. `status` and `is_default` are optional: an omitted one keeps the stored value, and an account that ends inactive is never the default. Compatibility of the accounting account with the treasury kind (type matrix and CxC/CxP/VAT/tax/posting reservations) is checked only when accounting_account_id changes; an existing association whose account is unchanged keeps saving. Requires `backoffice.treasury.treasury-accounts.manage`.", "operationId": "a974c22c110961413dd5eab3d1c65225", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "The ID of the treasury account to update", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "kind", "name", "currency", "accounting_account_id", "accounting_center_id" ], "properties": { "kind": { "description": "Must equal the stored kind.", "type": "string", "example": "bank", "enum": [ "bank", "wallet", "cash", "credit_card" ] }, "name": { "type": "string", "example": "Cuenta operativa", "maxLength": 100 }, "bank_name": { "description": "Required for kind bank; prohibited otherwise.", "type": "string", "example": "Banco de Venezuela", "nullable": true, "maxLength": 80 }, "account_number": { "description": "Required for kind bank; prohibited otherwise. 8 to 20 digits; spaces and hyphens are ignored.", "type": "string", "example": "0102-0123-4567-8901", "nullable": true, "maxLength": 30 }, "type": { "description": "Required for kind bank; prohibited otherwise.", "type": "string", "example": "corriente", "nullable": true, "enum": [ "corriente", "ahorro" ] }, "identifier": { "description": "Required for every kind except bank; prohibited for bank. A credit_card identifier is an alias such as `Visa •8452`, never the full card number.", "type": "string", "example": "tesoreria@empresa.com", "nullable": true, "maxLength": 120 }, "currency": { "type": "string", "example": "VES", "enum": [ "DOP", "USD", "VES", "USDT", "EUR" ] }, "accounting_account_id": { "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426655440000" }, "accounting_center_id": { "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426655440000" }, "is_default": { "description": "Optional; omit it to keep the stored flag (PUT …/default and …/deactivation own it). Default for its kind and currency; null is refused. Send a JSON boolean; 1 and 0, as numbers or strings, are read as true and false.", "type": "boolean", "example": false }, "status": { "description": "Optional; omit it to keep the stored status (prefer …/activation and …/deactivation). Turning inactive without `is_default` also stops the account being the default.", "type": "string", "example": "active", "enum": [ "active", "inactive" ] } }, "type": "object" } } } }, "responses": { "200": { "description": "Treasury account updated" }, "403": { "description": "The user lacks the manage permission" }, "404": { "description": "Treasury account not found", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "detail": { "type": "string", "example": "La cuenta de tesorería <123e4567-e89b-12d3-a456-426655440000> no existe" } }, "type": "object" } } } }, "409": { "description": "The account number or the identifier of that kind already exists, or the account is in use and its currency cannot change because a payment instrument, a collection or payment method line, or a treasury transfer (as source or destination, cancelled included) references it: treasury_account_number_already_exists, treasury_account_identifier_already_exists, treasury_account_currency_locked", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "detail": { "type": "string", "example": "Ya existe una cuenta de tesorería con este número de cuenta" } }, "type": "object" } } } }, "422": { "description": "Validation error, including treasury_account_kind_is_immutable, treasury_account_card_alias_is_a_card_number (a credit_card identifier holding 13+ consecutive digits once spaces, dashes or dots are removed, even when it is the stored one), or invalid_treasury_account_status when is_default is true and the requested or stored status is inactive; or an accounting account incompatible with the treasury kind when accounting_account_id changes: treasury_account_accounting_account_incompatible_type or treasury_account_accounting_account_reserved_by_role, with the message under errors.accounting_account_id.", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string", "example": "La cuenta 1.2.01. - Clientes está reservada como cuenta por cobrar; una cuenta de tesorería no puede usar una cuenta reservada a otro rol." }, "error_code": { "type": "string", "enum": [ "treasury_account_accounting_account_incompatible_type", "treasury_account_accounting_account_reserved_by_role", "treasury_account_kind_is_immutable", "treasury_account_card_alias_is_a_card_number" ] }, "errors": { "properties": { "accounting_account_id": { "type": "array", "items": { "type": "string" } } }, "type": "object" } }, "type": "object" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Internal Server Error" }, "status": { "type": "integer", "example": 500 }, "detail": { "type": "string", "example": "An unexpected error occurred while processing your request." } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Backoffice - Treasury - Treasury Accounts" ], "summary": "Delete a treasury account", "description": "Requires `backoffice.treasury.treasury-accounts.manage`.", "operationId": "5854c4b9e0b768d53fca24009b6bb373", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "The ID of the treasury account to delete", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Treasury account deleted" }, "403": { "description": "The user lacks the manage permission" }, "404": { "description": "Treasury account not found", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "detail": { "type": "string", "example": "La cuenta de tesorería <123e4567-e89b-12d3-a456-426655440000> no existe" } }, "type": "object" } } } }, "409": { "description": "A payment instrument, a collection or payment method line, or a treasury transfer (as source or destination, cancelled included) references the account; deactivate it instead: treasury_account_in_use", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "detail": { "type": "string", "example": "La cuenta de tesorería <123e4567-e89b-12d3-a456-426655440000> está en uso y no se puede eliminar; desactívala en su lugar" }, "error_code": { "type": "string", "example": "treasury_account_in_use" } }, "type": "object" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Internal Server Error" }, "status": { "type": "integer", "example": 500 }, "detail": { "type": "string", "example": "An unexpected error occurred while processing your request." } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/treasury/accounts": { "get": { "tags": [ "Backoffice - Treasury - Treasury Accounts" ], "summary": "Search the company's treasury accounts", "description": "Lists the company's treasury accounts with the code and name of their accounting account and center. Every list filter takes one value or several (`status=active` or `status[]=active&status[]=inactive`): values of one filter are alternatives, filters narrow each other, and an empty filter is ignored. `search` matches the bank name, the name, the currency or the identifier, and the account number by its digits, literally; it is trimmed of ASCII whitespace and a blank term searches nothing. `sort_by` defaults to `name`; without `sort_by` the order is ascending, and a `sort_by` sent without `sort_order` reads descending. `kind` and `currency` order by their stored codes, and ties are settled by id, ascending. `group_by=status` lists active accounts before inactive ones, ahead of the requested order and before paging. `meta.counts` counts the matching accounts by status under every filter but `status`, both statuses always present; it does not depend on the page, its size, the order or the grouping. A company without accounts returns an empty `items` list with `total` 0. Requires `backoffice.treasury.treasury-accounts.view`.", "operationId": "2567e4bc7789e473654a4b51873c7d12", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "description": "One status. Same as one `status[]`.", "required": false, "schema": { "type": "string", "enum": [ "active", "inactive" ] } }, { "name": "status[]", "in": "query", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "active", "inactive" ] }, "maxItems": 2 } }, { "name": "kind", "in": "query", "description": "One kind. Same as one `kind[]`.", "required": false, "schema": { "type": "string", "enum": [ "bank", "wallet", "cash", "credit_card" ] } }, { "name": "kind[]", "in": "query", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "bank", "wallet", "cash", "credit_card" ] }, "maxItems": 4 } }, { "name": "currency", "in": "query", "description": "One currency. Same as one `currency[]`.", "required": false, "schema": { "type": "string", "enum": [ "USD", "VES", "USDT", "EUR", "DOP" ] } }, { "name": "currency[]", "in": "query", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "USD", "VES", "USDT", "EUR", "DOP" ] }, "maxItems": 5 } }, { "name": "search", "in": "query", "description": "Matches the bank name, the name, the currency, the identifier or the account number digits; trimmed, and blank searches nothing.", "required": false, "schema": { "type": "string", "maxLength": 120 } }, { "name": "bankName", "in": "query", "description": "Legacy partial filter on the bank name.", "required": false, "schema": { "type": "string", "maxLength": 80 } }, { "name": "name", "in": "query", "description": "Legacy partial filter on the name.", "required": false, "schema": { "type": "string", "maxLength": 100 } }, { "name": "accountNumber", "in": "query", "description": "Legacy partial filter on the account number; its digits are matched when it has any.", "required": false, "schema": { "type": "string", "maxLength": 30 } }, { "name": "sort_by", "in": "query", "required": false, "schema": { "type": "string", "default": "name", "enum": [ "name", "kind", "currency", "created_at" ] } }, { "name": "sort_order", "in": "query", "description": "Ascending when `sort_by` is omitted; descending when `sort_by` is sent without it.", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "group_by", "in": "query", "description": "Active accounts first, then inactive ones, before the requested order and before paging.", "required": false, "schema": { "type": "string", "enum": [ "status" ] } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 100, "minimum": 1 } }, { "name": "perPage", "in": "query", "description": "Alias of `per_page`; `per_page` wins when both are sent.", "required": false, "deprecated": true, "schema": { "type": "integer", "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "A page of treasury accounts with the list's status counts", "content": { "application/json": { "schema": { "required": [ "items", "total", "per_page", "current_page", "meta" ], "properties": { "items": { "description": "Each item has the same fields, in the same order, as the detail.", "type": "array", "items": { "required": [ "id", "kind", "identifier", "bank_name", "name", "account_number", "type", "currency", "accounting_account_id", "accounting_account_code", "accounting_account_name", "accounting_center_id", "accounting_center_code", "accounting_center_name", "is_default", "status", "company_id", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426655440000" }, "kind": { "type": "string", "example": "bank", "enum": [ "bank", "wallet", "cash", "credit_card" ] }, "identifier": { "description": "Null for kind bank.", "type": "string", "example": null, "nullable": true }, "bank_name": { "description": "Null unless kind is bank.", "type": "string", "example": "Banco de Venezuela", "nullable": true }, "name": { "type": "string", "example": "Cuenta operativa" }, "account_number": { "description": "Null unless kind is bank.", "type": "string", "example": "01020123456789012345", "nullable": true }, "type": { "description": "Null unless kind is bank.", "type": "string", "example": "corriente", "nullable": true, "enum": [ "corriente", "ahorro" ] }, "currency": { "type": "string", "example": "VES", "enum": [ "DOP", "USD", "VES", "USDT", "EUR" ] }, "accounting_account_id": { "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426655440000" }, "accounting_account_code": { "type": "string", "example": "1101", "nullable": true }, "accounting_account_name": { "type": "string", "example": "Bancos", "nullable": true }, "accounting_center_id": { "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426655440000" }, "accounting_center_code": { "type": "string", "example": "CC1", "nullable": true }, "accounting_center_name": { "type": "string", "example": "Centro Norte", "nullable": true }, "is_default": { "type": "boolean", "example": false }, "status": { "type": "string", "example": "active", "enum": [ "active", "inactive" ] }, "company_id": { "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426655440000" }, "created_at": { "description": "When the account was created, as a UTC instant; null for an account without a stored creation time.", "type": "string", "format": "date-time", "example": "2026-10-14T16:58:51+00:00", "nullable": true } }, "type": "object" } }, "total": { "type": "integer", "example": 12 }, "per_page": { "type": "integer", "example": 20 }, "current_page": { "type": "integer", "example": 1 }, "meta": { "required": [ "counts" ], "properties": { "counts": { "description": "Matching accounts by status, under every filter but `status`.", "required": [ "active", "inactive" ], "properties": { "active": { "type": "integer", "example": 10 }, "inactive": { "type": "integer", "example": 2 } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks the view permission" }, "422": { "description": "Invalid filter, search, sort, grouping or pagination parameter; `errors` names it, `status.0` for the first status of a list", "content": { "application/json": { "schema": { "required": [ "title", "status", "detail", "errors" ], "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string", "example": "The given data was invalid." }, "error_code": { "type": "string", "example": null, "nullable": true }, "errors": { "description": "The offending query parameters, each with its messages.", "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Internal Server Error" }, "status": { "type": "integer", "example": 500 }, "detail": { "type": "string", "example": "An unexpected error occurred while processing your request." } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Treasury - Treasury Accounts" ], "summary": "Create a treasury account", "description": "Creates a treasury account of kind bank, wallet, cash or credit_card. Kind bank requires bank_name, account_number and type and prohibits identifier; every other kind requires identifier and prohibits the three bank fields. A credit_card identifier is an alias such as `Visa •8452`, never the full card number. The accounting account must match the kind's type matrix (asset for bank, wallet and cash; asset or liability for credit_card) and must not be reserved, whatever the designation's status, as a receivable account, payable account, VAT input account, tax account or posting account role. Accounts are never classified by name or code; group (parent) accounts are not rejected by the backend. Requires `backoffice.treasury.treasury-accounts.manage`.", "operationId": "e202852f8b499a4f395c50b805a18d97", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "id", "kind", "name", "currency", "accounting_account_id", "accounting_center_id", "is_default" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426655440000" }, "kind": { "type": "string", "example": "bank", "enum": [ "bank", "wallet", "cash", "credit_card" ] }, "name": { "type": "string", "example": "Cuenta operativa", "maxLength": 100 }, "bank_name": { "description": "Required for kind bank; prohibited otherwise.", "type": "string", "example": "Banco de Venezuela", "nullable": true, "maxLength": 80 }, "account_number": { "description": "Required for kind bank; prohibited otherwise. 8 to 20 digits; spaces and hyphens are ignored.", "type": "string", "example": "0102-0123-4567-8901", "nullable": true, "maxLength": 30 }, "type": { "description": "Required for kind bank; prohibited otherwise.", "type": "string", "example": "corriente", "nullable": true, "enum": [ "corriente", "ahorro" ] }, "identifier": { "description": "Required for every kind except bank; prohibited for bank. A wallet address or email, a cash fund label, or a credit card alias.", "type": "string", "example": "tesoreria@empresa.com", "nullable": true, "maxLength": 120 }, "currency": { "type": "string", "example": "VES", "enum": [ "DOP", "USD", "VES", "USDT", "EUR" ] }, "accounting_account_id": { "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426655440000" }, "accounting_center_id": { "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426655440000" }, "is_default": { "description": "Default for its kind and currency. Send a JSON boolean; 1 and 0, as numbers or strings, are read as true and false.", "type": "boolean", "example": false } }, "type": "object" } } } }, "responses": { "201": { "description": "Treasury account created" }, "403": { "description": "The user lacks the manage permission" }, "409": { "description": "The id, the account number or the identifier of that kind already exists: treasury_account_already_exists, treasury_account_number_already_exists, treasury_account_identifier_already_exists", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "detail": { "type": "string", "example": "Ya existe una cuenta de tesorería con este número de cuenta" } }, "type": "object" } } } }, "422": { "description": "Validation error; treasury_account_card_alias_is_a_card_number; accounting account incompatible with the treasury kind (treasury_account_accounting_account_incompatible_type or treasury_account_accounting_account_reserved_by_role); or treasury_account_position_backs_cash_register when the accounting account and currency already back a cash register.", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string", "example": "La cuenta 4.1.01. - Ingresos es de tipo Ingreso; una cuenta de tesorería de tipo bank debe ser de tipo Activo." }, "error_code": { "type": "string", "enum": [ "treasury_account_accounting_account_incompatible_type", "treasury_account_accounting_account_reserved_by_role", "treasury_account_card_alias_is_a_card_number", "treasury_account_position_backs_cash_register" ] }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Internal Server Error" }, "status": { "type": "integer", "example": 500 }, "detail": { "type": "string", "example": "An unexpected error occurred while processing your request." } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/treasury/transfers/{id}/cancel": { "post": { "tags": [ "Backoffice - Treasury - Treasury Transfers" ], "summary": "Cancel a treasury transfer", "description": "Cancels a posted treasury transfer by inverting every line of its entry in both books, dated at the company's today. Cancelling an already cancelled transfer writes nothing and answers the same. Requires `backoffice.treasury.treasury-transfers.manage`.", "operationId": "cancelTreasuryTransfer", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "The treasury transfer id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The transfer is cancelled", "content": { "application/json": { "schema": { "required": [ "id", "status", "cancelled_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "example": "cancelled", "enum": [ "posted", "cancelled" ] }, "cancelled_at": { "type": "string", "format": "date-time", "example": "2026-09-27T15:00:00+00:00", "nullable": true } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks the manage permission" }, "404": { "description": "The treasury transfer does not exist in this company (treasury_transfer_not_found), or the company itself does not (company_not_found)", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "detail": { "type": "string", "example": "La transferencia entre cuentas propias <0199a000-0000-7000-8000-000000000001> no existe" }, "error_code": { "type": "string", "example": "treasury_transfer_not_found" } }, "type": "object" } } } }, "422": { "description": "The id is not a UUID" }, "500": { "description": "Internal server error, such as a posted transfer without its entry (treasury_transfer_posted_transaction_missing) or an inversion that would not balance (invalid_transaction_balance) or would have no lines (empty_transaction_items), or a ledger write that failed (transaction_persistence_failed)", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Internal Server Error" }, "status": { "type": "integer", "example": 500 }, "detail": { "type": "string", "example": "An unexpected error occurred while processing your request." } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/treasury/transfers/{id}": { "get": { "tags": [ "Backoffice - Treasury - Treasury Transfers" ], "summary": "Get a treasury transfer", "description": "The transfer with the names of both accounts and the codes of its posted entry and of the entry that inverted it, what it is worth in each book, the Rate Snapshot it took and its differences by cause. A Currency Exchange with a bolívar side also shows its rate indicator, which compares its Effective Rate with the official rate it references and, for a viewer holding `backoffice.accounting.settings.exchange-rates.view`, with the latest Management Reference of its side observed by the end of its operation date: the `sell` one when it sells its dollar side (USD or USDT), the `buy` one when it buys it, never the other. An exchange between USD and USDT has no bolívar side and no indicator. Requires `backoffice.treasury.treasury-transfers.view`.", "operationId": "findTreasuryTransfer", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "The treasury transfer id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The treasury transfer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TreasuryTransferDetailResource" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks the view permission" }, "404": { "description": "The treasury transfer does not exist in this company: treasury_transfer_not_found", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "detail": { "type": "string", "example": "La transferencia entre cuentas propias <0199a000-0000-7000-8000-000000000001> no existe" }, "error_code": { "type": "string", "example": "treasury_transfer_not_found" } }, "type": "object" } } } }, "422": { "description": "The id is not a UUID" }, "500": { "description": "The stored transfer is corrupt: a valuation or a rate snapshot no rule produces (invalid_treasury_transfer_valuation, or a rate snapshot integrity error)", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Internal Server Error" }, "status": { "type": "integer", "example": 500 }, "detail": { "type": "string", "example": "An unexpected error occurred while processing your request." } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/treasury/transfers": { "get": { "tags": [ "Backoffice - Treasury - Treasury Transfers" ], "summary": "Search the company's treasury transfers", "description": "Lists the company's treasury transfers, newest operation date first (then newest recorded, then by id), with the names of both accounts, the codes of the posted entry and of its inversion, the Responsable and the labels. Every list filter takes one value or several (`status=posted` or `status[]=posted&status[]=cancelled`): values of one filter are alternatives, filters narrow each other, and an empty filter is ignored. `treasury_account_id` matches either side; `kind` with both values filters nothing. `search` matches the bank reference, the counterparty or the code of an entry the transfer posted or inverted, case-insensitively and literally. `sort_by` orders by the operation date or by when the transfer was recorded, ties settled by when it was recorded and then by id in the same direction. `meta.counts` counts the matching transfers by status under every filter but `status`, both statuses always present; `meta.label_counts` counts the matching transfers carrying each live label of the company under every filter but `label_ids`, `{}` when none; neither depends on the page, its size or the order. Each item shows what the transfer is worth in each book, the Rate Snapshot it took, its differences by cause and, for a Currency Exchange, its Effective Rate; the rate indicator is only on the detail. A company without transfers returns an empty `items` list with `total` 0. Requires `backoffice.treasury.treasury-transfers.view`.", "operationId": "searchTreasuryTransfers", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "operation_date_from", "in": "query", "description": "Inclusive.", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "operation_date_to", "in": "query", "description": "Inclusive; not before operation_date_from when both are sent.", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "treasury_account_id", "in": "query", "description": "One account, the source or the destination. Same as one `treasury_account_id[]`.", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "treasury_account_id[]", "in": "query", "description": "At most 50 accounts, each matching the source or the destination.", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 50 } }, { "name": "status", "in": "query", "description": "One status. Same as one `status[]`.", "required": false, "schema": { "type": "string", "enum": [ "posted", "cancelled" ] } }, { "name": "status[]", "in": "query", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "posted", "cancelled" ] }, "maxItems": 2 } }, { "name": "kind", "in": "query", "description": "`exchange` lists only Currency Exchanges, `same_currency` only transfers in one currency. Same as one `kind[]`.", "required": false, "schema": { "type": "string", "enum": [ "same_currency", "exchange" ] } }, { "name": "kind[]", "in": "query", "description": "Both values filter nothing.", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "same_currency", "exchange" ] }, "maxItems": 2 } }, { "name": "responsible_user_id", "in": "query", "description": "One Responsable, by user id. Same as one `responsible_user_id[]`.", "required": false, "schema": { "type": "string", "pattern": "^\\d+$", "example": "57" } }, { "name": "responsible_user_id[]", "in": "query", "description": "At most 50 Responsables, by user id.", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "pattern": "^\\d+$" }, "maxItems": 50 } }, { "name": "label_ids", "in": "query", "description": "One label. Same as one `label_ids[]`.", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "label_ids[]", "in": "query", "description": "At most 20 labels; a transfer carrying any of them matches while the label is live.", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 20 } }, { "name": "search", "in": "query", "description": "Matches the reference, the counterparty or an entry code; trimmed, and blank searches nothing.", "required": false, "schema": { "type": "string", "maxLength": 120 } }, { "name": "sort_by", "in": "query", "required": false, "schema": { "type": "string", "default": "operation_date", "enum": [ "operation_date", "created_at" ] } }, { "name": "sort_order", "in": "query", "required": false, "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "A page of treasury transfers with the list's facets", "content": { "application/json": { "schema": { "required": [ "items", "total", "per_page", "current_page", "meta" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/TreasuryTransferResource" } }, "total": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 20 }, "current_page": { "type": "integer", "example": 1 }, "meta": { "required": [ "counts", "label_counts" ], "properties": { "counts": { "description": "Matching transfers by status, under every filter but `status`.", "required": [ "posted", "cancelled" ], "properties": { "posted": { "type": "integer", "example": 35 }, "cancelled": { "type": "integer", "example": 2 } }, "type": "object" }, "label_counts": { "description": "Matching transfers by live label id, under every filter but `label_ids`; `{}` when none.", "type": "object", "additionalProperties": { "type": "integer" } } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks the view permission" }, "422": { "description": "Invalid filter, search, sort or pagination parameter; `errors` names it, `status.0` for the first status of a list", "content": { "application/json": { "schema": { "required": [ "title", "status", "detail", "errors" ], "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string", "example": "The given data was invalid." }, "errors": { "description": "The offending query parameters, each with its messages.", "type": "object" } }, "type": "object" } } } }, "500": { "description": "A stored transfer is corrupt: a valuation or a rate snapshot no rule produces (invalid_treasury_transfer_valuation, or a rate snapshot integrity error)", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Internal Server Error" }, "status": { "type": "integer", "example": 500 }, "detail": { "type": "string", "example": "An unexpected error occurred while processing your request." } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Treasury - Treasury Transfers" ], "summary": "Record a transfer between the company's own treasury accounts", "description": "Records a treasury transfer and posts its entry in one step: the destination account is debited and the source account credited, each on its own accounting account and center, dated at the operation date. Both accounts must be different active treasury accounts of this company. Money kept in both of the company's books posts at its own amount. Any other money the official USD/VES rate can value — USD, VES or USDT, for instance in a company keeping VES and USD books — is valued in both books by the Treasury Position of the source: the source relieves its carrying amount and the destination inherits exactly that. A destination whose position the transfer reduces, such as paying a credit card that owes, relieves its own carrying amount instead, and the gap with what the source relieved posts as a realized treasury_currency gain or loss on the destination's center. A Currency Exchange pairs USD, USDT and VES — USD for VES, USDT for VES or USD for USDT, either way — and requires `received_amount`; any other pair, such as one involving EUR or DOP, is refused with 422 treasury_transfer_currency_not_supported on `destination_treasury_account_id`. USDT is valued as USD at par at the official USD/VES rate: USDT received takes the official value of as many dollars, and USDT delivered relieves its carrying amount like any other money. The server derives its Effective Rate from the two amounts, never from the client, quoted like the official pair: units of the quote currency per unit of the base, where the base is USDT against USD or VES and USD against VES — bolívares per USD, bolívares per USDT or USD per USDT — whichever side was delivered, rounded half-up to 8 decimals, and keeps it as the agreed rate of a `negotiated` rate snapshot, next to the official rate it references, with the recording user (or the API key and the user who owns it) as responsible; a rate that rounds to zero or exceeds 999999999999.99999999 is refused with 422 treasury_transfer_effective_rate_out_of_range on `received_amount`. Every exchange takes the official USD/VES rate of the operation date, except a USD ↔ USDT exchange in a company keeping both books in USD, which converts nothing, takes no official rate and posts no `treasury_currency` (at 1:1 it posts no difference; any gap between the two amounts posts as `agreed_rate`): its rate snapshot is `negotiated` over an identity valuation (`rate` 1.00000000, `rate_reference` null). Otherwise its source relieves its own position against the official value it delivered and its destination takes the official value it received, unless it reduces its own position; the gaps post on the source's center as realized `treasury_currency` (official value delivered − carrying amount relieved) and `agreed_rate` (official value received − official value delivered) gains or losses, each in its own book, and a destination that reduces its position posts its own `treasury_currency` on its center. Fees never change the Effective Rate. Optional `fees` each leave the source or the destination in that account's currency: the expense posts at the official value of the operation date to the company's bank_fees posting account on the center of the account it leaves, the account is credited with the carrying amount it relieves, and any gap posts as a realized treasury_currency gain or loss; fees are valued after the transfer, in the order sent, so they never change what the transfer itself is worth. The official USD/VES rate of the operation date is taken for every exchange but that one, and otherwise when a source crosses zero (no balance, a liability, or more than it holds) or when a fee needs its official value; when no official rate can value it, the answer is 422 accounting_configuration_incomplete with `missing[0].reason_code` OFFICIAL_RATE_STALE (dated today) or OFFICIAL_RATE_NOT_AVAILABLE (earlier date). A transfer that posts a fee or a difference needs the posting accounts of those roles; when the company cannot post to one, the answer is 422 accounting_configuration_incomplete listing every missing role in `details` (TREASURY_POSTING_ACCOUNT_MISSING for bank_fees, EXCHANGE_POSTING_ACCOUNT_MISSING for realized_exchange_gain or realized_exchange_loss) and nothing is written. An amount worth 0.00 in both books is refused (422 treasury_transfer_amount_values_to_zero), and so is one worth more in a book than a ledger line holds, 9999999999999.99 (422 treasury_transfer_amount_exceeds_ledger_precision); both name `received_amount` when the received money of an exchange is the one refused, `delivered_amount` otherwise. The amounts are in each account's currency; omit `received_amount` when both accounts share a currency. The client generates the UUID `id`: resending the same id with the same terms, `received_amount` and fees included in the same order, answers 200 with the transfer as it stands, with other terms 409 treasury_transfer_id_conflict. Every 422 raised by a business rule names the offending request field under `errors`, `fees.N.treasury_account_id` or `fees.N.amount` for a fee. An optional `responsible_user_id` names the transfer's Responsable, who must be a current user of the company (422 on `errors.responsible_user_id` otherwise); a replay ignores it. Requires `backoffice.treasury.treasury-transfers.manage`.", "operationId": "recordTreasuryTransfer", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "id", "source_treasury_account_id", "destination_treasury_account_id", "delivered_amount", "operation_date", "credit_date" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "0199a000-0000-7000-8000-000000000001" }, "source_treasury_account_id": { "description": "The treasury account the money leaves.", "type": "string", "format": "uuid", "example": "0199a000-0000-7000-8000-00000000000a" }, "destination_treasury_account_id": { "description": "The treasury account the money reaches; different from the source.", "type": "string", "format": "uuid", "example": "0199a000-0000-7000-8000-00000000000b" }, "delivered_amount": { "description": "Decimal string greater than zero with at most 2 decimals, in the source account's currency.", "type": "string", "pattern": "^(?!0+(?:\\.0{1,2})?$)\\d{1,13}(?:\\.\\d{1,2})?$", "example": "500.00" }, "received_amount": { "description": "Decimal string greater than zero with at most 2 decimals, in the destination account's currency. Required when the two accounts keep different currencies (a Currency Exchange): what the destination received, from which the server derives the Effective Rate. Omit it or send null when both accounts share a currency: it is then the delivered amount, and a different one is refused.", "type": "string", "pattern": "^(?!0+(?:\\.0{1,2})?$)\\d{1,13}(?:\\.\\d{1,2})?$", "example": "150000.00", "nullable": true }, "operation_date": { "description": "The accounting date of the entry; not after the company's today.", "type": "string", "format": "date", "example": "2026-09-26" }, "credit_date": { "description": "When the money reached the destination; not before the operation date. Kept for reconciliation.", "type": "string", "format": "date", "example": "2026-09-27" }, "reference": { "description": "Optional bank reference; blank is stored as null.", "type": "string", "example": "000123456789", "nullable": true, "maxLength": 120 }, "counterparty": { "description": "Optional counterparty; blank is stored as null.", "type": "string", "example": "Banesco", "nullable": true, "maxLength": 120 }, "fees": { "description": "Optional Transfer Fees, at most 10, each leaving the source or the destination account in that account's currency. They are valued, stored and returned in the order sent; omit the field or send an empty list for none.", "type": "array", "items": { "required": [ "treasury_account_id", "amount" ], "properties": { "treasury_account_id": { "description": "The source or the destination treasury account the fee leaves.", "type": "string", "format": "uuid", "example": "0199a000-0000-7000-8000-00000000000a" }, "amount": { "description": "Decimal string greater than zero with at most 2 decimals, in the currency of the account the fee leaves.", "type": "string", "pattern": "^(?!0+(?:\\.0{1,2})?$)\\d{1,13}(?:\\.\\d{1,2})?$", "example": "1.00" } }, "type": "object", "additionalProperties": false }, "maxItems": 10 }, "responsible_user_id": { "description": "Optional Responsable: the id of a current user of the company, as a string; omit it or send null for none. It is no term of the transfer, so a replay of the same id ignores it.", "type": "string", "example": "57", "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Transfer recorded and its entry posted", "content": { "application/json": { "schema": { "required": [ "id", "status" ], "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "example": "posted", "enum": [ "posted", "cancelled" ] } }, "type": "object" } } } }, "200": { "description": "The same id was already recorded with the same terms; nothing was written and the transfer is answered as it stands", "content": { "application/json": { "schema": { "required": [ "id", "status" ], "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "example": "posted", "enum": [ "posted", "cancelled" ] } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks the manage permission" }, "404": { "description": "A treasury account does not exist in this company (treasury_transfer_treasury_account_not_found), or the company itself does not (company_not_found)", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "detail": { "type": "string", "example": "La cuenta de tesorería <0199a000-0000-7000-8000-00000000000a> no existe" }, "error_code": { "type": "string", "example": "treasury_transfer_treasury_account_not_found" } }, "type": "object" } } } }, "409": { "description": "The id is already used by a transfer with other terms: treasury_transfer_id_conflict", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "detail": { "type": "string", "example": "El identificador <0199a000-0000-7000-8000-000000000001> ya lo usa otra transferencia entre cuentas propias" }, "error_code": { "type": "string", "example": "treasury_transfer_id_conflict" } }, "type": "object" } } } }, "422": { "description": "Validation error (including `errors.responsible_user_id` when the Responsable is not a user of the company), or a business rule refused the transfer: treasury_transfer_same_account, treasury_transfer_treasury_account_inactive, treasury_transfer_currency_not_supported, treasury_transfer_fee_account_not_in_transfer, treasury_transfer_too_many_fees, treasury_transfer_amount_values_to_zero, treasury_transfer_amount_exceeds_ledger_precision, treasury_transfer_amount_not_positive, treasury_transfer_amount_currency_mismatch, treasury_transfer_amounts_differ, treasury_transfer_received_amount_required, treasury_transfer_effective_rate_out_of_range, treasury_transfer_operation_date_in_future, treasury_transfer_credit_date_before_operation_date, treasury_transfer_invalid_date, treasury_transfer_text_too_long, invalid_money. When no official rate can value the transfer or its fees, or the company cannot post to a posting account role the entry needs, the body is instead `{error: accounting_configuration_incomplete, missing[]}` with no `error_code`.", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string", "example": "Una transferencia entre cuentas propias no puede mover dinero de la cuenta de tesorería <0199a000-0000-7000-8000-00000000000a> a sí misma" }, "error_code": { "type": "string", "example": "treasury_transfer_same_account", "nullable": true }, "errors": { "description": "The offending request fields, each with its messages.", "type": "object" }, "error": { "description": "Only on an accounting readiness gap, which carries `missing` instead of the fields above.", "type": "string", "enum": [ "accounting_configuration_incomplete" ] }, "missing": { "description": "Only on an accounting readiness gap: the official rate that cannot value the transfer, or every posting account role its entry needs and the company cannot post to.", "type": "array", "items": { "required": [ "reason_code", "subject_type", "subject_id", "human_message", "details" ], "properties": { "reason_code": { "type": "string", "example": "OFFICIAL_RATE_STALE", "enum": [ "OFFICIAL_RATE_STALE", "OFFICIAL_RATE_NOT_AVAILABLE", "EXCHANGE_POSTING_ACCOUNT_MISSING", "TREASURY_POSTING_ACCOUNT_MISSING" ] }, "subject_type": { "type": "string", "example": "company" }, "subject_id": { "type": "string", "format": "uuid" }, "human_message": { "type": "string", "example": "La tasa oficial está vencida; carga una tasa oficial manual para continuar." }, "details": { "description": "For a rate gap, the pair, then the last known value date (stale) or the operation date (not available) when there is one; for a posting account gap, the missing role: bank_fees, realized_exchange_gain or realized_exchange_loss.", "type": "array", "items": { "type": "string" }, "example": [ "USD/VES", "2026-09-26" ] } }, "type": "object" } } }, "type": "object" } } } }, "500": { "description": "Internal server error, such as an entry that would not balance (invalid_transaction_balance) or would have no lines (empty_transaction_items), a ledger write that failed (transaction_persistence_failed), a Treasury Position with ledger lines without a side (treasury_position_has_unsided_ledger_lines), or a valuation no rule produces (invalid_treasury_transfer_valuation, a rate snapshot integrity error, or a settlement integrity error)", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Internal Server Error" }, "status": { "type": "integer", "example": 500 }, "detail": { "type": "string", "example": "An unexpected error occurred while processing your request." } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/treasury/transfers/{id}/responsible": { "put": { "tags": [ "Backoffice - Treasury - Treasury Transfers" ], "summary": "Reassign the Responsable of a treasury transfer", "description": "Sets or clears the Responsable of a posted treasury transfer. A cancelled transfer refuses any value, even the one it already has (409 treasury_transfer_responsible_cannot_be_reassigned). Sending the Responsable the transfer already has writes nothing and records no Activity. The value must be a current user of the company. The answer is an empty acknowledgement: read the transfer again for its new state. Requires `backoffice.treasury.treasury-transfers.manage`.", "operationId": "reassignTreasuryTransferResponsible", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "The treasury transfer id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "responsible_user_id" ], "properties": { "responsible_user_id": { "description": "The id of a user of the company, as a string, who becomes the Responsable; null clears it.", "type": "string", "example": "57", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "The Responsable is reassigned, or already was", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TreasuryTransferResponsibleAcknowledgement" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "The user lacks the manage permission" }, "404": { "description": "The treasury transfer does not exist in this company: treasury_transfer_not_found", "content": { "application/json": { "schema": { "required": [ "title", "status", "detail", "error_code" ], "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "detail": { "type": "string", "example": "La transferencia entre cuentas propias <0199a000-0000-7000-8000-000000000001> no existe" }, "error_code": { "type": "string", "example": "treasury_transfer_not_found" } }, "type": "object" } } } }, "409": { "description": "The transfer is cancelled: treasury_transfer_responsible_cannot_be_reassigned", "content": { "application/json": { "schema": { "required": [ "title", "status", "detail", "error_code" ], "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "detail": { "type": "string", "example": "La transferencia entre cuentas propias <0199a000-0000-7000-8000-000000000001> está en estado cancelled y su responsable no se puede reasignar" }, "error_code": { "type": "string", "example": "treasury_transfer_responsible_cannot_be_reassigned" } }, "type": "object" } } } }, "422": { "description": "The id is not a UUID, or `responsible_user_id` is missing, not a string or not a user of the company", "content": { "application/json": { "schema": { "required": [ "title", "status", "detail", "errors" ], "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string", "example": "The given data was invalid." }, "errors": { "description": "The offending request fields, each with its messages.", "type": "object" } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/users/{id}": { "get": { "tags": [ "Backoffice - Users" ], "summary": "Retrieve a user of the company by ID", "operationId": "bcb996bd07915986dc758d4fb35aa506", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "User ID", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "The user with its company role and timestamps; role_id and role_name are null when the user holds no role of the company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyUser" } } } }, "422": { "description": "The id is not a positive integer: errors.id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsersAndRolesProblem" } } } }, "404": { "description": "user_not_found: the user does not exist or is not a member of this company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsersAndRolesProblem" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unauthorized" }, "status": { "type": "integer", "example": 403 }, "detail": { "type": "string", "example": "You do not have permission to view this resource." } }, "type": "object" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Internal Server Error" }, "status": { "type": "integer", "example": 500 }, "detail": { "type": "string", "example": "An Unexpected Error Occurred" } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Backoffice - Users" ], "summary": "Update an existing user", "description": "Renames a user of this company and assigns its role. The email is not editable and is ignored.", "operationId": "94e6977ba9619110534c2c071c3adb72", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "description": "User ID", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "role_id" ], "properties": { "name": { "type": "string", "maxLength": 30, "minLength": 3 }, "role_id": { "description": "A role of this company, active or not. Another company's role or an unknown id answers 422.", "type": "integer", "example": 1 } }, "type": "object" } } } }, "responses": { "200": { "description": "User updated successfully" }, "422": { "description": "Field validation errors under errors, keyed by id, name and role_id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsersAndRolesProblem" } } } }, "404": { "description": "user_not_found: the user does not exist or is not a member of this company; nothing changes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsersAndRolesProblem" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unauthorized" }, "status": { "type": "integer", "example": 403 }, "detail": { "type": "string", "example": "You do not have permission to view this resource." } }, "type": "object" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Internal Server Error" }, "status": { "type": "integer", "example": 500 }, "detail": { "type": "string", "example": "An unexpected error occurred" } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/users": { "get": { "tags": [ "Backoffice - Users" ], "summary": "List the company's users with their role", "description": "Members of the company with the role each holds here. Unknown query keys are ignored.", "operationId": "115ebe8c6a58445aaefa8b43a02c91b7", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 100, "minimum": 1 } }, { "name": "search", "in": "query", "description": "Name or email, matched literally; empty means omitted.", "required": false, "schema": { "type": "string", "maxLength": 255 } }, { "name": "name", "in": "query", "description": "Name, matched literally; empty means omitted.", "required": false, "schema": { "type": "string", "maxLength": 255 } }, { "name": "email", "in": "query", "description": "Email, matched literally; empty means omitted.", "required": false, "schema": { "type": "string", "maxLength": 255 } }, { "name": "role_id", "in": "query", "description": "A role id of the company. Another company's or an unknown id matches nothing.", "required": false, "schema": { "type": "integer", "minimum": 1 } }, { "name": "role_id[]", "in": "query", "description": "Users holding any of these company roles.", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "integer", "minimum": 1 } } }, { "name": "sort_by", "in": "query", "description": "Default name ascending; a field without sort_order reads descending. The user id breaks ties in the same direction.", "required": false, "schema": { "type": "string", "default": "name", "enum": [ "name", "email" ] } }, { "name": "sort_order", "in": "query", "description": "Trimmed and case-insensitive.", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "group_by", "in": "query", "description": "role orders by role name, members without a role last, before the selected sort and before paging.", "required": false, "schema": { "type": "string", "enum": [ "role", "none" ] } } ], "responses": { "200": { "description": "A page of company users with the members per role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyUsersPage" } } } }, "422": { "description": "Field validation errors under errors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsersAndRolesProblem" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unauthorized" }, "status": { "type": "integer", "example": 403 }, "detail": { "type": "string", "example": "You do not have permission to view this resource." } }, "type": "object" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Internal Server Error" }, "detail": { "type": "string", "example": "An unexpected error occurred" }, "status": { "type": "integer", "example": 500 } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Backoffice - Users" ], "summary": "Create a new user", "operationId": "6366779489beb175b37a620420298144", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "email", "password", "role_id" ], "properties": { "name": { "type": "string", "example": "John Doe", "maxLength": 30, "minLength": 3 }, "email": { "type": "string", "format": "email", "example": "john.doe@example.com", "maxLength": 255 }, "password": { "type": "string", "example": "secretPassword123", "maxLength": 30, "minLength": 8 }, "role_id": { "description": "A role of this company, active or not. Another company's role or an unknown id answers 422.", "type": "integer", "example": 1 } }, "type": "object" } } } }, "responses": { "201": { "description": "User created. An email that already has an account adds that account to the company without changing it and returns its id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatedRecordId" } } } }, "422": { "description": "Field validation errors under errors, keyed by name, email, password and role_id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsersAndRolesProblem" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Unauthorized" }, "status": { "type": "integer", "example": 403 }, "detail": { "type": "string", "example": "You do not have permission to view this resource." } }, "type": "object" } } } }, "409": { "description": "The email belongs to a member of this company: user_already_member, with the reason also under errors.email. Nothing changes, the member's role included.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsersAndRolesProblem" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Internal Server Error" }, "status": { "type": "integer", "example": 500 }, "detail": { "type": "string", "example": "An unexpected error occurred while processing your request." } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/users/{id}/reactivate": { "post": { "tags": [ "Users" ], "summary": "Reactivate a company membership suspended on downgrade to Free", "operationId": "9bd5735368170522e9f85981601138a9", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "204": { "description": "Membership active; idempotent" }, "401": { "description": "Authentication required" }, "403": { "description": "Company access or users.update permission denied" }, "404": { "description": "Membership not found" }, "402": { "description": "Free requires Pro" }, "409": { "description": "Contracted user limit reached" }, "422": { "description": "Invalid user id" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/money-manager/{tenant}/accounts/{id}": { "get": { "tags": [ "MoneyManager - Accounts" ], "summary": "Get a specific money account by ID", "operationId": "61e929d583eb1c3124b54993fdf77bbb", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Money account details", "content": { "application/json": { "schema": { "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "cash", "bank", "credit_card", "savings" ] }, "balance": { "type": "string" }, "currency": { "type": "string" }, "icon": { "type": "string", "nullable": true }, "color": { "type": "string", "nullable": true }, "company_id": { "type": "string", "format": "uuid" } }, "type": "object" } } } }, "403": { "description": "Unauthorized" }, "404": { "description": "Account not found" } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "MoneyManager - Accounts" ], "summary": "Update an existing money account", "operationId": "3b24095f2bd514e98f71b09e5b08de50", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "type" ], "properties": { "name": { "type": "string", "maxLength": 255 }, "type": { "type": "string", "enum": [ "cash", "bank", "credit_card", "savings" ] } }, "type": "object" } } } }, "responses": { "200": { "description": "Account updated" }, "403": { "description": "Unauthorized" }, "404": { "description": "Account not found" }, "422": { "description": "Validation error" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "MoneyManager - Accounts" ], "summary": "Delete a money account", "operationId": "b835f674700e6d72490d0b14535ca847", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Account deleted" }, "403": { "description": "Unauthorized" }, "404": { "description": "Account not found" }, "422": { "description": "Account has non-zero balance" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/money-manager/{tenant}/accounts": { "get": { "tags": [ "MoneyManager - Accounts" ], "summary": "Search money accounts with filters and pagination", "operationId": "8ec83ab7107e22c304db65c6dfcfce51", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 20 } }, { "name": "sort_by", "in": "query", "description": "Any column of money_manager__accounts, bare or prefixed with the table name and a dot. Without it the list orders by name ascending. An empty value counts as absent. Any other value answers 422 invalid_list_sort.", "required": false, "schema": { "type": "string" } }, { "name": "sort_order", "in": "query", "description": "Checked even without sort_by, but it only orders a sort_by that is sent; a sort_by without it reads descending. Read ignoring case and surrounding spaces. An empty value counts as absent. Any other value answers 422 invalid_list_sort.", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Paginated list of money accounts", "content": { "application/json": { "schema": { "properties": { "items": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "cash", "bank", "credit_card", "savings" ] }, "balance": { "type": "string" }, "currency": { "type": "string" }, "icon": { "type": "string", "nullable": true }, "color": { "type": "string", "nullable": true }, "company_id": { "type": "string", "format": "uuid" } }, "type": "object" } }, "total": { "type": "integer" }, "per_page": { "type": "integer" }, "current_page": { "type": "integer" } }, "type": "object" } } } }, "403": { "description": "Unauthorized" }, "422": { "description": "invalid_list_sort: an unknown sort_by or a sort_order other than asc/desc; errors names the parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidListSortProblem" } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "MoneyManager - Accounts" ], "summary": "Create a new money account", "operationId": "5af440f3eb39175c2af9d4dbb7766312", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "type" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "maxLength": 255 }, "type": { "type": "string", "enum": [ "cash", "bank", "credit_card", "savings" ] }, "currency": { "type": "string", "default": "USD", "maxLength": 3 } }, "type": "object" } } } }, "responses": { "201": { "description": "Account created" }, "403": { "description": "Unauthorized" }, "422": { "description": "Validation error" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/money-manager/{tenant}/categories": { "get": { "tags": [ "MoneyManager - Categories" ], "summary": "Search categories with pagination", "operationId": "474488a427435d6c902968a99eb9132b", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 20 } }, { "name": "sort_by", "in": "query", "description": "Any column of money_manager__categories, bare or prefixed with the table name and a dot. Without it the list orders by name ascending. An empty value counts as absent. Any other value answers 422 invalid_list_sort.", "required": false, "schema": { "type": "string" } }, { "name": "sort_order", "in": "query", "description": "Checked even without sort_by, but it only orders a sort_by that is sent; a sort_by without it reads descending. Read ignoring case and surrounding spaces. An empty value counts as absent. Any other value answers 422 invalid_list_sort.", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Paginated list of categories", "content": { "application/json": { "schema": { "properties": { "items": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "icon": { "type": "string" }, "color": { "type": "string" }, "type": { "type": "string", "enum": [ "income", "expense", "both" ] }, "company_id": { "type": "string", "format": "uuid" }, "is_default": { "type": "boolean" } }, "type": "object" } }, "total": { "type": "integer" }, "per_page": { "type": "integer" }, "current_page": { "type": "integer" } }, "type": "object" } } } }, "403": { "description": "Unauthorized" }, "422": { "description": "invalid_list_sort: an unknown sort_by or a sort_order other than asc/desc; errors names the parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidListSortProblem" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/money-manager/{tenant}/categories/{id}": { "get": { "tags": [ "MoneyManager - Categories" ], "summary": "Get a specific category by ID", "operationId": "90fe8c51f79223ce8439c9ff4ed9cd7e", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Category details", "content": { "application/json": { "schema": { "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "icon": { "type": "string" }, "color": { "type": "string" }, "type": { "type": "string", "enum": [ "income", "expense", "both" ] }, "company_id": { "type": "string", "format": "uuid" }, "is_default": { "type": "boolean" } }, "type": "object" } } } }, "403": { "description": "Unauthorized" }, "404": { "description": "Category not found" } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "MoneyManager - Categories" ], "summary": "Update an existing category", "operationId": "bf52dd4941c60db1257303351f2235f5", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "icon", "color", "type" ], "properties": { "name": { "type": "string", "maxLength": 255 }, "icon": { "type": "string", "maxLength": 100 }, "color": { "type": "string", "maxLength": 50 }, "type": { "type": "string", "enum": [ "income", "expense", "both" ] } }, "type": "object" } } } }, "responses": { "200": { "description": "Category updated" }, "403": { "description": "Unauthorized" }, "404": { "description": "Category not found" }, "422": { "description": "Validation error" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "MoneyManager - Categories" ], "summary": "Delete a category", "operationId": "b58ef8af0b26d396b6c55c46bef0555d", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Category deleted" }, "403": { "description": "Unauthorized" }, "404": { "description": "Category not found" }, "422": { "description": "Category has transactions" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/money-manager/{tenant}/household/invites/{id}/accept": { "post": { "tags": [ "MoneyManager - Household" ], "summary": "Accept a household invitation", "operationId": "bfec73375e2421774db00d8a92da89c3", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Invitation accepted successfully" }, "403": { "description": "Unauthorized" }, "404": { "description": "Invitation not found" }, "409": { "description": "Invitation already accepted" }, "410": { "description": "Invitation expired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/money-manager/{tenant}/household/invites": { "get": { "tags": [ "MoneyManager - Household" ], "summary": "Search household invites with pagination", "operationId": "68d13591bbfee8e836b89d45531ab312", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 20 } }, { "name": "sort_by", "in": "query", "description": "Any column of money_manager__household_invites, bare or prefixed with the table name and a dot. Without it the list orders by created_at descending. An empty value counts as absent. Any other value answers 422 invalid_list_sort.", "required": false, "schema": { "type": "string" } }, { "name": "sort_order", "in": "query", "description": "Checked even without sort_by, but it only orders a sort_by that is sent; a sort_by without it reads descending. Read ignoring case and surrounding spaces. An empty value counts as absent. Any other value answers 422 invalid_list_sort.", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Paginated list of household invites", "content": { "application/json": { "schema": { "properties": { "items": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "email": { "type": "string" }, "role": { "type": "string", "enum": [ "admin", "editor", "viewer" ] }, "status": { "type": "string", "enum": [ "pending", "accepted", "rejected", "expired" ] }, "company_id": { "type": "string", "format": "uuid" }, "invited_by_user_id": { "description": "The id of the user who sent the invite, as a string.", "type": "string" }, "expires_at": { "description": "ISO 8601 in UTC, with microseconds.", "type": "string", "format": "date-time", "example": "2026-10-25T12:34:56.000000Z" } }, "type": "object" } }, "total": { "type": "integer" }, "per_page": { "type": "integer" }, "current_page": { "type": "integer" } }, "type": "object" } } } }, "403": { "description": "Unauthorized" }, "422": { "description": "invalid_list_sort: an unknown sort_by or a sort_order other than asc/desc; errors names the parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidListSortProblem" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/money-manager/{tenant}/recurrence-rules/{id}": { "get": { "tags": [ "MoneyManager - RecurrenceRules" ], "summary": "Get a specific recurrence rule by ID", "operationId": "1e2ab482a32b5df028104265310b060a", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Recurrence rule details", "content": { "application/json": { "schema": { "properties": { "id": { "type": "string", "format": "uuid" }, "source_transaction_id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "recurrence_type": { "type": "string", "enum": [ "repeat", "installment" ] }, "frequency": { "type": "string" }, "installment_total": { "type": "integer", "nullable": true }, "installments_created": { "type": "integer" }, "next_due_date": { "type": "string", "format": "date" }, "status": { "type": "string", "enum": [ "active", "paused", "completed", "cancelled" ] }, "created_by_user_id": { "type": "string" }, "type": { "type": "string", "nullable": true }, "amount": { "type": "string", "nullable": true }, "category_id": { "type": "string", "format": "uuid", "nullable": true }, "account_id": { "type": "string", "format": "uuid", "nullable": true }, "to_account_id": { "type": "string", "format": "uuid", "nullable": true }, "note": { "type": "string", "nullable": true }, "category_name": { "type": "string", "nullable": true }, "category_icon": { "type": "string", "nullable": true }, "category_color": { "type": "string", "nullable": true }, "account_name": { "type": "string", "nullable": true } }, "type": "object" } } } }, "403": { "description": "Unauthorized" }, "404": { "description": "Recurrence rule not found" } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "MoneyManager - RecurrenceRules" ], "summary": "Edit a recurrence rule's template and schedule (future-only)", "operationId": "15c4d4eb8370975ed13d83fa372ce96d", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "amount": { "type": "string", "example": "60.00" }, "category_id": { "type": "string", "format": "uuid" }, "account_id": { "type": "string", "format": "uuid" }, "note": { "type": "string" }, "frequency": { "type": "string", "enum": [ "daily", "weekdays", "weekend", "weekly", "every_2_weeks", "every_4_weeks", "semi_monthly", "monthly", "end_of_month", "every_2_months", "every_3_months", "every_4_months", "every_6_months", "annually" ] }, "next_due_date": { "type": "string", "format": "date" } }, "type": "object" } } } }, "responses": { "200": { "description": "Recurrence rule updated", "content": { "application/json": { "schema": { "properties": { "id": { "type": "string", "format": "uuid" }, "source_transaction_id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "recurrence_type": { "type": "string", "enum": [ "repeat", "installment" ] }, "frequency": { "type": "string" }, "installment_total": { "type": "integer", "nullable": true }, "installments_created": { "type": "integer" }, "next_due_date": { "type": "string", "format": "date" }, "status": { "type": "string", "enum": [ "active", "paused", "completed", "cancelled" ] }, "created_by_user_id": { "type": "string" }, "type": { "type": "string", "nullable": true }, "amount": { "type": "string", "nullable": true }, "category_id": { "type": "string", "format": "uuid", "nullable": true }, "account_id": { "type": "string", "format": "uuid", "nullable": true }, "to_account_id": { "type": "string", "format": "uuid", "nullable": true }, "note": { "type": "string", "nullable": true }, "category_name": { "type": "string", "nullable": true }, "category_icon": { "type": "string", "nullable": true }, "category_color": { "type": "string", "nullable": true }, "account_name": { "type": "string", "nullable": true } }, "type": "object" } } } }, "403": { "description": "Unauthorized" }, "404": { "description": "Recurrence rule not found" }, "409": { "description": "Version conflict" }, "422": { "description": "Validation error" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "MoneyManager - RecurrenceRules" ], "summary": "Cancel/delete a recurrence rule", "operationId": "2a5e6161926cb81ab9f175d34c0236e0", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Recurrence rule cancelled" }, "400": { "description": "Invalid request" }, "403": { "description": "Unauthorized" }, "404": { "description": "Recurrence rule not found" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/money-manager/{tenant}/recurrence-rules/{id}/pause": { "put": { "tags": [ "MoneyManager - RecurrenceRules" ], "summary": "Pause a recurrence rule", "operationId": "f2739e436694d19178a3e40c4d28666e", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Recurrence rule paused" }, "400": { "description": "Rule is not active" }, "403": { "description": "Unauthorized" }, "404": { "description": "Recurrence rule not found" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/money-manager/{tenant}/recurrence-rules": { "get": { "tags": [ "MoneyManager - RecurrenceRules" ], "summary": "Search recurrence rules with filters and pagination", "operationId": "58a88a2018b44bfba5ffac81ea542341", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 20 } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "active", "paused", "completed", "cancelled" ] } }, { "name": "recurrence_type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "repeat", "installment" ] } } ], "responses": { "200": { "description": "Paginated list of recurrence rules", "content": { "application/json": { "schema": { "properties": { "items": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "source_transaction_id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "recurrence_type": { "type": "string" }, "frequency": { "type": "string" }, "installment_total": { "type": "integer", "nullable": true }, "installments_created": { "type": "integer" }, "next_due_date": { "type": "string", "format": "date" }, "status": { "type": "string" }, "created_by_user_id": { "type": "string" }, "type": { "type": "string", "nullable": true }, "amount": { "type": "string", "nullable": true }, "category_id": { "type": "string", "format": "uuid", "nullable": true }, "account_id": { "type": "string", "format": "uuid", "nullable": true }, "to_account_id": { "type": "string", "format": "uuid", "nullable": true }, "note": { "type": "string", "nullable": true }, "category_name": { "type": "string", "nullable": true }, "category_icon": { "type": "string", "nullable": true }, "category_color": { "type": "string", "nullable": true }, "account_name": { "type": "string", "nullable": true } }, "type": "object" } }, "total": { "type": "integer" }, "per_page": { "type": "integer" }, "current_page": { "type": "integer" } }, "type": "object" } } } }, "403": { "description": "Unauthorized" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "MoneyManager - RecurrenceRules" ], "summary": "Create a new recurrence rule", "operationId": "be378b61750fa74add5b59ee111c6b2c", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "id", "source_transaction_id", "recurrence_type", "frequency" ], "properties": { "id": { "type": "string", "format": "uuid" }, "source_transaction_id": { "type": "string", "format": "uuid" }, "recurrence_type": { "type": "string", "enum": [ "repeat", "installment" ] }, "frequency": { "type": "string", "enum": [ "daily", "weekdays", "weekend", "weekly", "every_2_weeks", "every_4_weeks", "monthly", "end_of_month", "every_2_months", "every_3_months", "every_4_months", "every_6_months", "annually" ] }, "installment_total": { "type": "integer", "nullable": true, "minimum": 2 } }, "type": "object" } } } }, "responses": { "201": { "description": "Recurrence rule created" }, "403": { "description": "Unauthorized" }, "422": { "description": "Validation error" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/money-manager/{tenant}/recurrence-rules/{id}/resume": { "put": { "tags": [ "MoneyManager - RecurrenceRules" ], "summary": "Resume a paused recurrence rule", "operationId": "9f65cd28737b629921351dc79e8fe7cb", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Recurrence rule resumed" }, "400": { "description": "Rule is not paused" }, "403": { "description": "Unauthorized" }, "404": { "description": "Recurrence rule not found" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/money-manager/{tenant}/transactions/{id}": { "get": { "tags": [ "MoneyManager - Transactions" ], "summary": "Get a specific transaction by ID with enriched data", "operationId": "285ec2d9fe0ef6187001c1ec0408f7b2", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Transaction details with enriched data", "content": { "application/json": { "schema": { "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "income", "expense", "transfer" ] }, "amount": { "type": "string" }, "date": { "type": "string", "format": "date" }, "note": { "type": "string", "nullable": true }, "company_id": { "type": "string", "format": "uuid" }, "created_by_user_id": { "type": "string" }, "parent_transaction_id": { "type": "string", "format": "uuid", "nullable": true }, "category_id": { "type": "string", "format": "uuid", "nullable": true }, "category_name": { "type": "string", "nullable": true }, "category_icon": { "type": "string", "nullable": true }, "category_color": { "type": "string", "nullable": true }, "account_id": { "type": "string", "format": "uuid" }, "account_name": { "type": "string" }, "to_account_id": { "type": "string", "format": "uuid", "nullable": true }, "to_account_name": { "type": "string", "nullable": true }, "fee_amount": { "description": "Amount of the linked transfer-fee transaction, when one exists", "type": "string", "nullable": true }, "fee_account_id": { "description": "Account the linked transfer fee is debited from", "type": "string", "format": "uuid", "nullable": true }, "created_by_user_name": { "type": "string" }, "recurrence_rule": { "properties": { "id": { "type": "string", "format": "uuid" }, "recurrence_type": { "type": "string" }, "frequency": { "type": "string", "example": "monthly" }, "status": { "type": "string" }, "installment_total": { "type": "integer", "nullable": true }, "installments_created": { "type": "integer" }, "next_due_date": { "type": "string", "format": "date" } }, "type": "object", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" } } } }, "403": { "description": "Unauthorized" }, "404": { "description": "Transaction not found" } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "MoneyManager - Transactions" ], "summary": "Update an existing transaction", "operationId": "8000bf5813ae83bac51d2ad1d616a9db", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "type", "amount", "date", "account_id", "note" ], "properties": { "type": { "type": "string", "enum": [ "income", "expense", "transfer" ] }, "amount": { "type": "number", "minimum": 0.01 }, "date": { "type": "string", "format": "date" }, "category_id": { "description": "Required for income, nullable for expense and transfer", "type": "string", "format": "uuid", "nullable": true }, "account_id": { "type": "string", "format": "uuid" }, "to_account_id": { "type": "string", "format": "uuid", "nullable": true }, "note": { "type": "string", "maxLength": 500 }, "fee_amount": { "description": "Transfer fee. Omit to leave the fee untouched, send null to remove it, send a value to create or update it", "type": "number", "nullable": true, "minimum": 0.01 }, "fee_account_id": { "description": "Account the fee is debited from; must be the transfer source or destination. Defaults to the current fee account, or the destination for a new fee", "type": "string", "format": "uuid", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Transaction updated" }, "403": { "description": "Unauthorized" }, "404": { "description": "Transaction not found" }, "422": { "description": "Validation error" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "MoneyManager - Transactions" ], "summary": "Delete a transaction", "operationId": "0175a7f5c4195b37d10c0570b30cad0a", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Transaction deleted" }, "403": { "description": "Unauthorized" }, "404": { "description": "Transaction not found" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/money-manager/{tenant}/transactions": { "get": { "tags": [ "MoneyManager - Transactions" ], "summary": "Search transactions with filters, pagination, and enriched data", "operationId": "ea201818fde18f41467552074eacec30", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 20 } } ], "responses": { "200": { "description": "Paginated list of enriched transactions", "content": { "application/json": { "schema": { "properties": { "items": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "income", "expense", "transfer" ] }, "amount": { "type": "string" }, "date": { "type": "string", "format": "date" }, "note": { "type": "string", "nullable": true }, "company_id": { "type": "string", "format": "uuid" }, "created_by_user_id": { "type": "string" }, "parent_transaction_id": { "type": "string", "format": "uuid", "nullable": true }, "category_id": { "type": "string", "format": "uuid", "nullable": true }, "category_name": { "type": "string", "nullable": true }, "category_icon": { "type": "string", "nullable": true }, "category_color": { "type": "string", "nullable": true }, "account_id": { "type": "string", "format": "uuid" }, "account_name": { "type": "string" }, "to_account_id": { "type": "string", "format": "uuid", "nullable": true }, "to_account_name": { "type": "string", "nullable": true }, "created_by_user_name": { "type": "string" }, "recurrence_rule": { "properties": { "id": { "type": "string", "format": "uuid" }, "recurrence_type": { "type": "string" }, "frequency": { "type": "string", "example": "monthly" }, "status": { "type": "string" }, "installment_total": { "type": "integer", "nullable": true }, "installments_created": { "type": "integer" }, "next_due_date": { "type": "string", "format": "date" } }, "type": "object", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" } }, "total": { "type": "integer" }, "per_page": { "type": "integer" }, "current_page": { "type": "integer" } }, "type": "object" } } } }, "403": { "description": "Unauthorized" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "MoneyManager - Transactions" ], "summary": "Create a new transaction", "operationId": "fce07035bda433b14fefd0c695884ebf", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "id", "type", "amount", "date", "account_id", "note" ], "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "income", "expense", "transfer" ] }, "amount": { "type": "number", "minimum": 0.01 }, "date": { "type": "string", "format": "date" }, "category_id": { "description": "Required for income/expense, omit for transfers", "type": "string", "format": "uuid", "nullable": true }, "account_id": { "type": "string", "format": "uuid" }, "to_account_id": { "type": "string", "format": "uuid", "nullable": true }, "note": { "type": "string", "maxLength": 500 }, "fee_amount": { "description": "Fee amount for transfers, prohibited for other types", "type": "number", "nullable": true, "minimum": 0.01 }, "fee_account_id": { "description": "Account the fee is debited from; must be the transfer source or destination. Defaults to the destination account", "type": "string", "format": "uuid", "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Transaction created" }, "403": { "description": "Unauthorized" }, "422": { "description": "Validation error" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/money-manager/{tenant}/transactions/summary": { "get": { "tags": [ "MoneyManager - Transactions" ], "summary": "Get transaction summary (income, expense, balance) for a given month", "operationId": "a7540cfd139f6e456b5ac3c276af3c28", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "month", "in": "query", "required": true, "schema": { "type": "integer", "maximum": 12, "minimum": 1 } }, { "name": "year", "in": "query", "required": true, "schema": { "type": "integer", "maximum": 2100, "minimum": 2000 } } ], "responses": { "200": { "description": "Transaction summary", "content": { "application/json": { "schema": { "properties": { "income": { "type": "string" }, "expense": { "type": "string" }, "total": { "type": "string" }, "month": { "type": "integer" }, "year": { "type": "integer" } }, "type": "object" } } } }, "403": { "description": "Unauthorized" }, "422": { "description": "Validation error" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/phone-verification/verifications/{id}/consume": { "post": { "tags": [ "PhoneVerification - Verifications" ], "summary": "Consume an approved phone verification", "description": "Requires an ordinary managed API key bound to the resolved tenant (company_id set, audience null). Browser sessions and personal tokens are forbidden. Reports that the device which started the flow claimed the approval. The verification becomes consumed, its expected sender is dropped, and it can never be claimed again. Every non-approved state answers the same 409 code, so the endpoint cannot be used to learn what became of an id.", "operationId": "a30a82339f0f98fe0d0700b2dc36f9ec", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Verification consumed", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "enum": [ "consumed" ] } }, "type": "object" } } } }, "401": { "description": "Missing, invalid, expired or revoked bearer credentials", "content": { "application/json": { "schema": { "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "403": { "description": "Session or unbound personal token; missing write ability on writes; or tenant membership/access denied", "content": { "application/json": { "schema": { "required": [ "title", "status", "detail" ], "properties": { "title": { "type": "string", "example": "Forbidden" }, "status": { "type": "integer", "example": 403 }, "detail": { "type": "string", "example": "You do not have permission to access this resource." }, "reason": { "type": "string" } }, "type": "object" } } } }, "404": { "description": "Opaque wrong-company, unresolved-tenant or audience denial; or consumer/verification not found", "content": { "application/json": { "schema": { "oneOf": [ { "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Recurso no encontrado" } }, "type": "object" }, { "required": [ "title", "status", "detail" ], "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "detail": { "type": "string" }, "error_code": { "type": "string", "example": "phone_verification_not_found" } }, "type": "object" } ] } } } }, "409": { "description": "The verification is pending, already consumed, expired or exhausted", "content": { "application/json": { "schema": { "properties": { "error_code": { "type": "string", "example": "phone_verification_not_consumable" } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/phone-verification/verifications/{id}": { "get": { "tags": [ "PhoneVerification - Verifications" ], "summary": "Read the state of a phone verification", "description": "Requires an ordinary managed API key bound to the resolved tenant (company_id set, audience null). Browser sessions and personal tokens are forbidden. Never returns the verification code. A verification belonging to another consumer company is reported as not found.", "operationId": "f769abe72a64824cbc39c7667ec8b531", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Verification state", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "enum": [ "pending", "approved", "consumed", "expired", "exhausted" ] }, "last_refusal": { "properties": { "reason": { "type": "string", "enum": [ "sender_mismatch", "rate_limited" ] }, "at": { "type": "string", "format": "date-time" } }, "type": "object", "nullable": true }, "expires_at": { "type": "string", "format": "date-time" } }, "type": "object" } } } }, "401": { "description": "Missing, invalid, expired or revoked bearer credentials", "content": { "application/json": { "schema": { "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "403": { "description": "Session or unbound personal token; missing write ability on writes; or tenant membership/access denied", "content": { "application/json": { "schema": { "required": [ "title", "status", "detail" ], "properties": { "title": { "type": "string", "example": "Forbidden" }, "status": { "type": "integer", "example": 403 }, "detail": { "type": "string", "example": "You do not have permission to access this resource." }, "reason": { "type": "string" } }, "type": "object" } } } }, "404": { "description": "Opaque wrong-company, unresolved-tenant or audience denial; or consumer/verification not found", "content": { "application/json": { "schema": { "oneOf": [ { "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Recurso no encontrado" } }, "type": "object" }, { "required": [ "title", "status", "detail" ], "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "detail": { "type": "string" }, "error_code": { "type": "string", "example": "phone_verification_not_found" } }, "type": "object" } ] } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/phone-verification/verifications": { "post": { "tags": [ "PhoneVerification - Verifications" ], "summary": "Register a phone verification and mint its verification code", "description": "Requires an ordinary managed API key bound to the resolved tenant (company_id set, audience null). Browser sessions and personal tokens are forbidden. Returns the verification code in clear exactly once. Only its keyed digest is stored.", "operationId": "842c51e5e8c9b95ed254986792a01ac3", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "expected_sender_e164" ], "properties": { "expected_sender_e164": { "description": "The phone the customer will write from, in E.164 with a leading + and no whatsapp: prefix. Spaces and dashes are stripped before the E.164 rule is applied, so '+58 414-1234567' is accepted; no pattern is published because any pattern would be tighter than what the server accepts.", "type": "string", "example": "+584141234567", "maxLength": 32 } }, "type": "object" } } } }, "responses": { "201": { "description": "Verification registered", "content": { "application/json": { "schema": { "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string", "pattern": "^[A-Z]{3}-[A-HJ-NP-Z2-9]{6}$", "example": "CAL-7K3Q9X" }, "wa_me_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "verification_phone_e164": { "type": "string", "example": "+584248274759" }, "expires_at": { "type": "string", "format": "date-time" } }, "type": "object" } } } }, "401": { "description": "Missing, invalid, expired or revoked bearer credentials", "content": { "application/json": { "schema": { "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "403": { "description": "Session or unbound personal token; missing write ability on writes; or tenant membership/access denied", "content": { "application/json": { "schema": { "required": [ "title", "status", "detail" ], "properties": { "title": { "type": "string", "example": "Forbidden" }, "status": { "type": "integer", "example": 403 }, "detail": { "type": "string", "example": "You do not have permission to access this resource." }, "reason": { "type": "string" } }, "type": "object" } } } }, "404": { "description": "Opaque wrong-company, unresolved-tenant or audience denial; or consumer/verification not found", "content": { "application/json": { "schema": { "oneOf": [ { "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Recurso no encontrado" } }, "type": "object" }, { "required": [ "title", "status", "detail" ], "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "detail": { "type": "string" }, "error_code": { "type": "string", "example": "phone_verification_not_found" } }, "type": "object" } ] } } } }, "409": { "description": "Could not mint a unique verification code" }, "422": { "description": "Validation error" }, "429": { "description": "The consumer company crossed its per-minute or per-day request ceiling", "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Too Many Requests" }, "status": { "type": "integer", "example": 429 }, "error_code": { "type": "string", "example": "phone_verification_consumer_ceiling_exceeded" } }, "type": "object" } } } }, "402": { "$ref": "#/components/responses/SubscriptionAccessRequired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/webhooks/twilio/whatsapp/{segment}/fallback": { "post": { "tags": [ "PhoneVerification - Webhooks" ], "summary": "Receive a signed inbound WhatsApp message Twilio could not deliver to the primary webhook", "description": "Carries no bearer token and no session: the request is authenticated by its X-Twilio-Signature header — declared above as the twilioSignature scheme — computed by Twilio over the configured public URL plus the /fallback suffix. That suffix is load-bearing — the Fallback URL in the Twilio Console must be the primary URL plus /fallback or every delivery here answers 403. A wrong path segment, and every segment while none is configured, answers 404 with the not-found body the router renders before any other phone-verification setting is read, so it discloses nothing about the right segment and raises no alarm. It records that the delivery happened and nothing else: no matching, no transition, no reply. A MessageSid the primary already recorded is a no-op, leaving the existing row untouched. Answers 200 with an empty TwiML Response in every non-error case; every error path raised inside the controller is standard Problem JSON. Throttled at 120 requests per minute in its own bucket, separate from the primary; that 429 is rendered by Laravel from the middleware pipeline. A required phone-verification setting that is not configured answers 500 with the body Laravel renders, because it fails while the controller is being built.", "operationId": "0ecdd80741b2e46f4e2aa2c4c064cf24", "parameters": [ { "name": "segment", "in": "path", "description": "Random unguessable path element agreed with Twilio, the same one the primary webhook uses.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "required": [ "MessageSid", "From" ], "properties": { "MessageSid": { "description": "Twilio's identifier for this delivery; one the primary already recorded is a no-op.", "type": "string", "maxLength": 34 }, "From": { "description": "The sender, with Twilio's whatsapp: transport prefix. Stored only as a keyed digest.", "type": "string", "example": "whatsapp:+584141234567" }, "ErrorCode": { "description": "Twilio's diagnostic for why the primary webhook failed; 11200 is an HTTP retrieval failure. NO LENGTH OR FORMAT RESTRICTION IS PUBLISHED BECAUSE THE ENDPOINT ENFORCES NONE: any value is accepted and the delivery still answers 200. It is stored as-is only when it is one to eight digits, and stored as null otherwise — an odd diagnostic never costs the row, so a client must never be told to withhold one.", "type": "string", "example": "11200" }, "Body": { "description": "The customer's message. Received because Twilio signs it, and DELIBERATELY NEVER STORED — the Mensaje entrante table has no body column.", "type": "string" }, "ErrorUrl": { "description": "The primary webhook URL that failed. Received because Twilio signs it, and DELIBERATELY NEVER STORED.", "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "description": "Acknowledged. The body is always the empty TwiML Response element: this route never replies to the customer", "content": { "text/xml": { "schema": { "type": "string" } } } }, "400": { "description": "A field of the delivery is malformed: the sender is not an E.164 number, or the MessageSid is not Twilio-shaped. The rejected value is never echoed back. A malformed ErrorCode is NOT one of these — it is recorded as null and the delivery still lands." }, "403": { "description": "Missing or invalid X-Twilio-Signature, including a signature computed over the primary URL instead of this one" }, "404": { "description": "Unknown path segment, or no segment configured. Answered by a middleware before the controller is built, so its body is the not-found message envelope Laravel renders, not the Problem JSON one." }, "429": { "description": "Rate limit exceeded. Rendered by the Laravel throttler from the middleware pipeline, so its body is the message envelope Laravel renders, not the Problem JSON one." }, "500": { "description": "The signature could not be verified, the delivery could not be recorded, or a required phone-verification setting is not configured." } }, "security": [ { "twilioSignature": [] } ] } }, "/api/webhooks/twilio/whatsapp/{segment}": { "post": { "tags": [ "PhoneVerification - Webhooks" ], "summary": "Receive a signed inbound WhatsApp message from Twilio", "description": "Carries no bearer token and no session: the request is authenticated by its X-Twilio-Signature header — declared above as the twilioSignature scheme — computed by Twilio over the configured public URL. A wrong path segment, and every segment while none is configured, answers 404 with the not-found body the router renders before any other phone-verification setting is read, so it discloses nothing about the right segment and raises no alarm. Answers 200 with TwiML; every error path raised inside the controller is standard Problem JSON. Throttled at 120 requests per minute; that 429 is rendered by Laravel from the middleware pipeline, so it carries the message body Laravel renders rather than the Problem envelope. A required phone-verification setting that is not configured answers 500 with the body Laravel renders, because it fails while the controller is being built.", "operationId": "ef80f5000def77d67558fe67ddeadcab", "parameters": [ { "name": "segment", "in": "path", "description": "Random unguessable path element agreed with Twilio.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "required": [ "MessageSid", "From", "Body", "NumMedia" ], "properties": { "MessageSid": { "description": "Twilio's identifier for this delivery; a repeat is a no-op.", "type": "string", "maxLength": 34 }, "From": { "description": "The sender, with Twilio's whatsapp: transport prefix.", "type": "string", "example": "whatsapp:+584141234567" }, "Body": { "description": "The customer's message. Its contents are deliberately not described, and are never stored or logged.", "type": "string" }, "NumMedia": { "description": "Attachment count. Media is never downloaded.", "type": "string", "example": "0" } }, "type": "object" } } } }, "responses": { "200": { "description": "Acknowledged, with the TwiML reply to send back (an empty Response element when there is nothing to say)", "content": { "text/xml": { "schema": { "type": "string" } } } }, "400": { "description": "A field of the delivery is malformed: the sender is not an E.164 number, or the MessageSid is not Twilio-shaped. The rejected value is never echoed back." }, "403": { "description": "Missing or invalid X-Twilio-Signature" }, "404": { "description": "Unknown path segment, or no segment configured. Answered by a middleware before the controller is built, so its body is the not-found message envelope Laravel renders, not the Problem JSON one." }, "409": { "description": "The verification was settled by a concurrent delivery" }, "429": { "description": "Rate limit exceeded. Rendered by the Laravel throttler from the middleware pipeline, so its body is the message envelope Laravel renders, not the Problem JSON one." }, "500": { "description": "The signature could not be verified, the delivery could not be recorded, or a required phone-verification setting is not configured." } }, "security": [ { "twilioSignature": [] } ] } }, "/api/storefront/buyers/verifications": { "post": { "tags": [ "Storefront" ], "operationId": "e65f09a7f78059cc035f7b3081250c23", "parameters": [ { "name": "x-buyer-device-id", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 128, "minLength": 8 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "phone" ], "properties": { "phone": { "description": "E.164; spaces and dashes are normalized before identity matching.", "type": "string" } }, "type": "object" } } } }, "responses": { "201": { "description": "Verification created; only this device may poll or claim it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorefrontBuyerVerification" } } } }, "404": { "description": "PhoneVerification consumer not configured" }, "422": { "description": "Invalid phone or device" }, "429": { "description": "Verification rate limit" } }, "security": [ { "storefrontKeyBearer": [] } ] } }, "/api/storefront/buyers/verifications/{id}": { "get": { "tags": [ "Storefront" ], "operationId": "e69adb6573d00cd2fd52ac9c79e00e04", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-buyer-device-id", "in": "header", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Verification state without phone or code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorefrontBuyerVerificationState" } } } }, "409": { "description": "Opaque unavailable verification" } }, "security": [ { "storefrontKeyBearer": [] } ] } }, "/api/storefront/buyers/sessions": { "post": { "tags": [ "Storefront" ], "operationId": "8af0e6309d9c7c8908b7bc98ab673729", "parameters": [ { "name": "x-buyer-device-id", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "verification_id" ], "properties": { "verification_id": { "type": "string", "format": "uuid" } }, "type": "object" } } } }, "responses": { "201": { "description": "Buyer and secure opaque Set-Cookie; no bearer in JSON", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorefrontBuyer" } } } }, "409": { "description": "Unavailable verification; no session issued" } }, "security": [ { "storefrontKeyBearer": [] } ] } }, "/api/storefront/buyers/session": { "get": { "tags": [ "Storefront" ], "operationId": "cf9cb38664b9feafb951e48cc8b9ce3a", "parameters": [ { "name": "x-buyer-device-id", "in": "header", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Private current buyer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorefrontBuyer" } } } }, "401": { "description": "Invalid, expired, revoked or device-mismatched session; cookie cleared" } }, "security": [ { "storefrontKeyBearer": [], "buyerSessionCookie": [] } ] }, "delete": { "tags": [ "Storefront" ], "operationId": "3954319dbe6fa4bd07c4111ee372dce7", "responses": { "204": { "description": "Session revoked and secure cookie expired, including repeated logout" } }, "security": [ { "storefrontKeyBearer": [] } ] } }, "/api/storefront/buyers/profile": { "put": { "tags": [ "Storefront" ], "operationId": "0aefbd30a3eac7075158e6d8a1f4ac24", "parameters": [ { "name": "x-buyer-device-id", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "consent", "consent_version" ], "properties": { "name": { "type": "string", "maxLength": 255 }, "email": { "type": "string", "format": "email", "nullable": true }, "consent": { "type": "boolean", "enum": [ true ] }, "consent_version": { "type": "string", "enum": [ "1" ] } }, "type": "object" } } } }, "responses": { "200": { "description": "Consented buyer linked to exactly one Client", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorefrontBuyer" } } } }, "401": { "description": "Buyer session required" }, "422": { "description": "Name and current consent required" } }, "security": [ { "storefrontKeyBearer": [], "buyerSessionCookie": [] } ] } }, "/api/storefront/categories": { "get": { "tags": [ "Storefront" ], "summary": "List visible categories for the Clave de Vitrina's channel", "operationId": "4c0d6c9422b98a4e4ee7d8bddd771c0a", "responses": { "200": { "description": "Active categories with at least one visible product", "headers": { "Cache-Control": { "description": "Storefront responses are never cached", "schema": { "type": "string", "example": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorefrontCatalogCategoriesResponse" } } } }, "401": { "description": "invalid_storefront_key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorefrontCatalogProblem" } } } }, "403": { "description": "origin_not_allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorefrontCatalogProblem" } } } }, "429": { "description": "Per-IP auth-failure or per-key request budget exhausted", "content": { "application/json": { "schema": { "required": [ "message" ], "properties": { "message": { "type": "string" } }, "type": "object" } } } } }, "security": [ { "storefrontKeyBearer": [] } ] } }, "/api/storefront/channel": { "get": { "tags": [ "Storefront" ], "summary": "Return the Clave de Vitrina's sales channel", "operationId": "de71753713f5e8ac547fc9965acf4974", "responses": { "200": { "description": "Channel bound to the authenticated key", "headers": { "Cache-Control": { "description": "Storefront responses are never cached", "schema": { "type": "string", "example": "no-store" } }, "Access-Control-Allow-Origin": { "description": "Echo of Origin when it belongs to this channel (never credentials)", "schema": { "type": "string", "example": "https://tienda.example.com" } }, "Vary": { "description": "Present with Access-Control-Allow-Origin so caches key by Origin", "schema": { "type": "string", "example": "Origin" } } }, "content": { "application/json": { "schema": { "required": [ "code", "name", "kind", "has_price_list", "price_list_currency", "low_stock_threshold" ], "properties": { "code": { "type": "string", "example": "DETAL" }, "name": { "type": "string", "example": "Vitrina detal" }, "kind": { "type": "string", "example": "storefront" }, "has_price_list": { "type": "boolean", "example": true }, "price_list_currency": { "type": "string", "example": "USD", "nullable": true }, "low_stock_threshold": { "type": "integer", "example": null, "nullable": true } }, "type": "object" } } } }, "401": { "description": "invalid_storefront_key — missing, malformed, unknown, revoked, or channel unusable", "headers": { "Cache-Control": { "description": "Never cache auth failures", "schema": { "type": "string", "example": "no-store" } }, "WWW-Authenticate": { "description": "Bearer challenge for the storefront surface", "schema": { "type": "string", "example": "Bearer realm=\"storefront\"" } } }, "content": { "application/json": { "schema": { "required": [ "title", "status", "detail", "error_code" ], "properties": { "title": { "type": "string", "example": "Unauthorized" }, "status": { "type": "integer", "example": 401 }, "detail": { "type": "string", "example": "Invalid storefront key." }, "error_code": { "type": "string", "example": "invalid_storefront_key" } }, "type": "object" } } } }, "403": { "description": "origin_not_allowed — Origin present but not on this key's channel", "headers": { "Cache-Control": { "description": "Never cache origin refusals", "schema": { "type": "string", "example": "no-store" } } }, "content": { "application/json": { "schema": { "required": [ "title", "status", "detail", "error_code" ], "properties": { "title": { "type": "string", "example": "Forbidden" }, "status": { "type": "integer", "example": 403 }, "detail": { "type": "string", "example": "Origin not allowed." }, "error_code": { "type": "string", "example": "origin_not_allowed" } }, "type": "object" } } } }, "429": { "description": "Per-IP auth-failure or per-key request budget exhausted", "headers": { "Retry-After": { "description": "Seconds until the bucket replenishes", "schema": { "type": "integer" } }, "Cache-Control": { "description": "Never cache throttled responses", "schema": { "type": "string", "example": "no-store" } } }, "content": { "application/json": { "schema": { "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "type": "object" } } } } }, "security": [ { "storefrontKeyBearer": [] } ] } }, "/api/storefront/offers": { "get": { "tags": [ "Storefront" ], "summary": "Live offers for visible items: channel price, bolívares and stock status", "description": "Never caches. Never publishes quantities. Omits non-visible item_ids. MER-4192 / ADR 0289.", "operationId": "2c19b5eb55fae1cd415a61863c987155", "parameters": [ { "name": "item_ids", "in": "query", "description": "1–100 distinct UUIDs, comma-separated; response preserves request order among visible items", "required": true, "schema": { "type": "string", "example": "0199c000-0000-7000-8000-0000000000a1,0199c000-0000-7000-8000-0000000000a2" } } ], "responses": { "200": { "description": "Offers for visible items; Cache-Control: no-store", "headers": { "Cache-Control": { "description": "Storefront responses are never cached", "schema": { "type": "string", "example": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorefrontOffersResponse" } } } }, "401": { "description": "invalid_storefront_key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorefrontCatalogProblem" } } } }, "403": { "description": "origin_not_allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorefrontCatalogProblem" } } } }, "422": { "description": "storefront_offer_item_ids_invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorefrontCatalogProblem" } } } }, "429": { "description": "Throttle exhausted", "content": { "application/json": { "schema": { "required": [ "message" ], "properties": { "message": { "type": "string" } }, "type": "object" } } } } }, "security": [ { "storefrontKeyBearer": [] } ] } }, "/api/storefront/web-orders/{id}/payment-reports": { "get": { "tags": [ "Storefront" ], "operationId": "0d9cbc79d35b818ffc398bb1db22c40c", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-buyer-device-id", "in": "header", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Private immutable report history", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WebOrderPaymentReport" } } } } }, "401": { "description": "Storefront key or buyer session required", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/StorefrontCatalogProblem" }, { "$ref": "#/components/schemas/WebOrderBuyerSessionRequired" } ] } } } }, "404": { "description": "Opaque missing or foreign order", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderPaymentProblem" } } } } }, "security": [ { "storefrontKeyBearer": [], "buyerSessionCookie": [] } ] }, "post": { "tags": [ "Storefront" ], "operationId": "09109a26f1e05d3b8592bba822a0a478", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-buyer-device-id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 128, "minLength": 8 } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "version", "reference", "proof" ], "properties": { "version": { "type": "integer", "minimum": 1 }, "reference": { "type": "string", "maxLength": 80, "minLength": 1 }, "reason": { "type": "string", "nullable": true, "maxLength": 200, "minLength": 1 }, "proof": { "description": "JPEG/PNG/WebP; MIME must match extension; at most8MiB and4096px per side; privately reencoded before transition.", "type": "string", "format": "binary" } }, "type": "object" } } } }, "responses": { "201": { "description": "Atomic report or exact durable replay; first review_due_at never moves", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderReported" } } } }, "401": { "description": "Storefront key or buyer session required", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/StorefrontCatalogProblem" }, { "$ref": "#/components/schemas/WebOrderBuyerSessionRequired" } ] } } } }, "404": { "description": "Opaque missing or foreign order", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderPaymentProblem" } } } }, "409": { "description": "Expired, stale version, missing rail, three-report limit or command conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderPaymentProblem" } } } }, "422": { "description": "Invalid multipart fields or unsafe evidence", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderPaymentProblem" } } } }, "503": { "description": "Private storage unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderPaymentProblem" } } } } }, "security": [ { "storefrontKeyBearer": [], "buyerSessionCookie": [] } ] } }, "/api/storefront/web-orders/{id}/payment-reports/{reportId}/evidence": { "get": { "tags": [ "Storefront" ], "operationId": "afc09b4900307090ac37df226f8baad9", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "reportId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-buyer-device-id", "in": "header", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Privately streamed sanitized image; no object URL", "content": { "image/jpeg": { "schema": { "type": "string", "format": "binary" } }, "image/png": { "schema": { "type": "string", "format": "binary" } }, "image/webp": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Storefront key or buyer session required", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/StorefrontCatalogProblem" }, { "$ref": "#/components/schemas/WebOrderBuyerSessionRequired" } ] } } } }, "404": { "description": "Opaque missing or foreign report", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderPaymentProblem" } } } }, "503": { "description": "Private evidence unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderPaymentProblem" } } } } }, "security": [ { "storefrontKeyBearer": [], "buyerSessionCookie": [] } ] } }, "/api/storefront/products/{productId}": { "get": { "tags": [ "Storefront" ], "summary": "Return one visible product by model:{uuid} or item:{uuid}", "operationId": "a6da73906c3cd7627efdf42cbc9b5200", "parameters": [ { "name": "productId", "in": "path", "description": "model:{uuid} or item:{uuid}", "required": true, "schema": { "type": "string", "example": "model:0199c000-0000-7000-8000-0000000000m1" } } ], "responses": { "200": { "description": "Visible product with variants and images; no price or stock", "headers": { "Cache-Control": { "description": "Storefront responses are never cached", "schema": { "type": "string", "example": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorefrontCatalogProduct" } } } }, "401": { "description": "invalid_storefront_key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorefrontCatalogProblem" } } } }, "403": { "description": "origin_not_allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorefrontCatalogProblem" } } } }, "404": { "description": "storefront_product_not_found — missing, not visible, or malformed id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorefrontCatalogProblem" } } } }, "429": { "description": "Per-IP auth-failure or per-key request budget exhausted", "content": { "application/json": { "schema": { "required": [ "message" ], "properties": { "message": { "type": "string" } }, "type": "object" } } } } }, "security": [ { "storefrontKeyBearer": [] } ] } }, "/api/storefront/products": { "get": { "tags": [ "Storefront" ], "summary": "List visible products for the Clave de Vitrina's channel", "operationId": "7aa7f980fda9978fc9bbddb99bc0f194", "parameters": [ { "name": "category_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 100 } }, { "name": "option", "in": "query", "description": "Name:Value filter; case and accent insensitive; keeps matching variants only", "required": false, "schema": { "type": "string", "example": "Color:rojo" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 24, "maximum": 48, "minimum": 1 } } ], "responses": { "200": { "description": "Paged visible products (Modelos and orphan items); no price or stock", "headers": { "Cache-Control": { "description": "Storefront responses are never cached", "schema": { "type": "string", "example": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorefrontCatalogProductsPage" } } } }, "401": { "description": "invalid_storefront_key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorefrontCatalogProblem" } } } }, "403": { "description": "origin_not_allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorefrontCatalogProblem" } } } }, "422": { "description": "Validation failed (e.g. per_page > 48)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorefrontCatalogProblem" } } } }, "429": { "description": "Per-IP auth-failure or per-key request budget exhausted", "content": { "application/json": { "schema": { "required": [ "message" ], "properties": { "message": { "type": "string" } }, "type": "object" } } } } }, "security": [ { "storefrontKeyBearer": [] } ] } }, "/api/storefront/web-orders/quote": { "post": { "tags": [ "Storefront" ], "operationId": "faeef3ced27565fe56f6491ec84a66c2", "parameters": [ { "name": "x-buyer-device-id", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 128, "minLength": 8 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderCart" } } } }, "responses": { "401": { "description": "Buyer session or storefront authentication required", "content": { "application/json": { "schema": { "oneOf": [ { "required": [ "message" ], "properties": { "message": { "type": "string" } }, "type": "object" }, { "required": [ "error_code", "detail" ], "properties": { "error_code": { "type": "string" }, "detail": { "type": "string" } }, "type": "object" } ] } } } }, "200": { "description": "Signed server-priced preview or reservable buyer quote; no-store", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderQuote" } } } }, "409": { "description": "QUOTE_STALE (an item is no longer on the channel), empty_cart, item_unavailable, rate_unavailable or rail_unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderPaymentProblem" } } } }, "422": { "description": "Invalid input or device", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderPaymentProblem" } } } } }, "security": [ { "storefrontKeyBearer": [] } ] } }, "/api/storefront/web-orders": { "get": { "tags": [ "Storefront" ], "operationId": "536871d41cfdf0057d2493f67974e908", "parameters": [ { "name": "x-buyer-device-id", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 128, "minLength": 8 } } ], "responses": { "200": { "description": "Latest 50 private orders; no-store", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WebOrder" } } } } }, "401": { "description": "Buyer session required" } }, "security": [ { "storefrontKeyBearer": [], "buyerSessionCookie": [] } ] }, "post": { "tags": [ "Storefront" ], "operationId": "87491654edb0d7956a2944d2ec11b938", "parameters": [ { "name": "x-buyer-device-id", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 128, "minLength": 8 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 128, "minLength": 8 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderReserve" } } } }, "responses": { "201": { "description": "Order and all stock holds committed; retries replay exact original", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrder" } } } }, "401": { "description": "Buyer session required" }, "409": { "description": "idempotency_conflict; QUOTE_STALE, for an expired, foreign or changed quote and for a reservation TTL in force that differs from the one the quote showed; buyer_has_live_order; reservation_policy_missing or reservation_policy_open_time_unavailable; or insufficient_stock, which names each short line by item_id only: never a quantity or a location", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderReserveProblem" } } } }, "422": { "description": "Profile, consent, notice opt-in or input invalid" }, "503": { "description": "web_order_reservations_paused: an operator stopped new reservations, before any lock, retries included. The order of a lost response stays readable through GET web-orders.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderPaymentProblem" } } } } }, "security": [ { "storefrontKeyBearer": [], "buyerSessionCookie": [] } ] } }, "/api/storefront/web-orders/{id}": { "get": { "tags": [ "Storefront" ], "operationId": "1eb5056209d9dde9b23c8ad1b8b8ae70", "parameters": [ { "name": "x-buyer-device-id", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 128, "minLength": 8 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "401": { "description": "Buyer session or storefront authentication required", "content": { "application/json": { "schema": { "oneOf": [ { "required": [ "message" ], "properties": { "message": { "type": "string" } }, "type": "object" }, { "required": [ "error_code", "detail" ], "properties": { "error_code": { "type": "string" }, "detail": { "type": "string" } }, "type": "object" } ] } } } }, "200": { "description": "Private order and the rails it can still choose from; no-store", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrderDetail" } } } }, "404": { "description": "Opaque missing or foreign order" } }, "security": [ { "storefrontKeyBearer": [], "buyerSessionCookie": [] } ] } }, "/api/storefront/web-orders/{id}/cancel": { "post": { "tags": [ "Storefront" ], "operationId": "ed752b5313f1590ff9deeccf2d84321a", "parameters": [ { "name": "x-buyer-device-id", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 128, "minLength": 8 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 128, "minLength": 8 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "422": { "description": "Invalid input or idempotency key", "content": { "application/json": { "schema": { "oneOf": [ { "required": [ "message", "errors" ], "properties": { "message": { "type": "string" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" }, { "$ref": "#/components/schemas/StorefrontCatalogProblem" } ] } } } }, "401": { "description": "Buyer session or storefront authentication required", "content": { "application/json": { "schema": { "oneOf": [ { "required": [ "message" ], "properties": { "message": { "type": "string" } }, "type": "object" }, { "required": [ "error_code", "detail" ], "properties": { "error_code": { "type": "string" }, "detail": { "type": "string" } }, "type": "object" } ] } } } }, "200": { "description": "Cancelled once; reported or terminal state returned unchanged", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrder" } } } }, "404": { "description": "Opaque missing or foreign order" }, "409": { "description": "Idempotency conflict" } }, "security": [ { "storefrontKeyBearer": [], "buyerSessionCookie": [] } ] } }, "/api/storefront/web-orders/{id}/rail": { "patch": { "tags": [ "Storefront" ], "operationId": "38bd74c97e8362ca1f1d0c2fb9b78f76", "parameters": [ { "name": "x-buyer-device-id", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 128, "minLength": 8 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 128, "minLength": 8 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "rail_id", "version" ], "properties": { "rail_id": { "type": "string", "format": "uuid" }, "version": { "type": "integer", "minimum": 1 } }, "type": "object" } } } }, "responses": { "422": { "description": "Invalid input or idempotency key", "content": { "application/json": { "schema": { "oneOf": [ { "required": [ "message", "errors" ], "properties": { "message": { "type": "string" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" }, { "$ref": "#/components/schemas/StorefrontCatalogProblem" } ] } } } }, "401": { "description": "Buyer session or storefront authentication required", "content": { "application/json": { "schema": { "oneOf": [ { "required": [ "message" ], "properties": { "message": { "type": "string" } }, "type": "object" }, { "required": [ "error_code", "detail" ], "properties": { "error_code": { "type": "string" }, "detail": { "type": "string" } }, "type": "object" } ] } } } }, "200": { "description": "Versioned terms changed, deadline retained", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebOrder" } } } }, "404": { "description": "Opaque missing or foreign order" }, "409": { "description": "Checked in this order: web_order_expired (its deadline passed, or it expired); web_order_version_conflict (stale version or any other state); rail_unavailable; idempotency_conflict for a reused key" } }, "security": [ { "storefrontKeyBearer": [], "buyerSessionCookie": [] } ] } }, "/api/backoffice/{tenant}/subscription/payment-reports": { "post": { "tags": [ "Subscriptions" ], "summary": "Report the Company subscription payment", "operationId": "c9436f0799b9a9f9098c02af404c9d93", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/PaymentReportInput" } } } }, "responses": { "201": { "description": "New pending report or equivalent pending/validated/rejected replay; access_status is the current Subscription state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentReportResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionMessage" } } } }, "403": { "description": "Membership or Superadmin denied", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/SubscriptionAccessDenied" }, { "$ref": "#/components/schemas/SubscriptionMessage" } ] } } } }, "404": { "description": "Unknown Company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionMessage" } } } }, "409": { "description": "Unverified email or report conflict", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/SubscriptionUnverifiedEmail" }, { "$ref": "#/components/schemas/SubscriptionProblem" } ] } } } }, "422": { "description": "Invalid fields or proof", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/SubscriptionProblem" }, { "$ref": "#/components/schemas/PaymentReportValidation" } ] } } } }, "503": { "description": "Rate, payment configuration or private storage unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionProblem" } } } }, "500": { "description": "Unexpected failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionProblem" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/{tenant}/subscription": { "get": { "tags": [ "Subscriptions" ], "summary": "Read the access state of the subscription covering the current company", "description": "Verified company membership is sufficient. The raw stored state is returned even when the gate is disabled. The state is that of the Suscripción covering the company: one Suscripción, held by a Compañía titular, covers every Company created from inside the ERP and is paid per contracted user, never per Company. Companies without a Suscripción have implicit managed access and no contracted seats.", "operationId": "c2a78fb683b27eb0a7764323ddadae6d", "parameters": [ { "name": "requested_seats", "in": "query", "description": "Free upgrade quote, 1–50 users; existing Pro agreements retain their seats.", "schema": { "type": "integer", "maximum": 50, "minimum": 1 } }, { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "422": { "description": "Invalid requested seat count", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentReportValidation" } } } }, "200": { "description": "Current subscription access state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionAccessState" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionMessage" } } } }, "403": { "description": "Company access or tenant membership denied", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/SubscriptionAccessDenied" }, { "$ref": "#/components/schemas/SubscriptionMessage" } ] } } } }, "404": { "description": "Unknown company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionMessage" } } } }, "409": { "description": "Email unverified", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionUnverifiedEmail" } } } }, "500": { "description": "Unexpected read failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionProblem" } } } } }, "security": [ { "bearerAuth": [] } ] } } }, "components": { "schemas": { "ActionProposalResponse": { "required": [ "id", "action", "status", "expires_at", "expired", "summary", "warnings", "result", "error_code" ], "properties": { "id": { "type": "string", "format": "uuid" }, "action": { "type": "string" }, "status": { "type": "string", "enum": [ "proposed", "approved", "rejected", "confirming", "confirmed", "failed" ] }, "expires_at": { "type": "string", "format": "date-time" }, "expired": { "type": "boolean" }, "summary": { "type": "object", "additionalProperties": true }, "warnings": { "type": "array", "items": { "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "type": "object" } }, "result": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "code": { "type": "string" }, "status": { "type": "string" }, "status_label": { "type": "string" }, "url": { "type": "string", "nullable": true } }, "type": "object", "nullable": true, "additionalProperties": true }, "error_code": { "description": "Stored confirm outcome error code when status is failed; not an HTTP Problem error_code", "type": "string", "nullable": true } }, "type": "object", "additionalProperties": false }, "UsageAdmissionInput": { "required": [ "subjectToken", "attemptId", "sessionId", "turnId", "stepId", "attempt", "model", "priceVersionId", "input", "cacheWrite5m", "cacheWrite1h", "cacheRead", "maxTokens", "images" ], "properties": { "function": { "description": "Optional backoffice-assistant function. Omitted and explicit in_app have the same historical replay digest. Any supplied function from an authenticated WhatsApp client is rejected with 422.", "type": "string", "default": "in_app", "enum": [ "in_app", "system_one" ] }, "subjectToken": { "description": "Current assistant-channel token; never an MCP token. Re-authentication with a rotated same-scope token preserves replay.", "type": "string", "maxLength": 4096, "minLength": 1 }, "attemptId": { "description": "Stable UUIDv7. Reuse after uncertain transport; never infer twice from replay.", "type": "string", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$", "maxLength": 36, "minLength": 36 }, "sessionId": { "description": "Finite execution identity; server derives principal and Company.", "type": "string", "maxLength": 128, "minLength": 1 }, "turnId": { "description": "Finite execution identity; server derives principal and Company.", "type": "string", "maxLength": 128, "minLength": 1 }, "stepId": { "description": "Finite execution identity; server derives principal and Company.", "type": "string", "maxLength": 128, "minLength": 1 }, "attempt": { "description": "Finite execution identity; server derives principal and Company.", "type": "string", "maxLength": 128, "minLength": 1 }, "model": { "description": "Finite execution identity; server derives principal and Company.", "type": "string", "maxLength": 128, "minLength": 1 }, "priceVersionId": { "description": "Must match the server-selected effective immutable tariff.", "type": "string", "pattern": "^[a-f0-9]{64}$", "maxLength": 64, "minLength": 64 }, "input": { "description": "Finite disjoint maximum units; all categories required, explicit zero when unsupported.", "type": "string", "pattern": "^(0|[1-9][0-9]{0,11})$", "maxLength": 12, "minLength": 1 }, "cacheWrite5m": { "description": "Finite disjoint maximum units; all categories required, explicit zero when unsupported.", "type": "string", "pattern": "^(0|[1-9][0-9]{0,11})$", "maxLength": 12, "minLength": 1 }, "cacheWrite1h": { "description": "Finite disjoint maximum units; all categories required, explicit zero when unsupported.", "type": "string", "pattern": "^(0|[1-9][0-9]{0,11})$", "maxLength": 12, "minLength": 1 }, "cacheRead": { "description": "Finite disjoint maximum units; all categories required, explicit zero when unsupported.", "type": "string", "pattern": "^(0|[1-9][0-9]{0,11})$", "maxLength": 12, "minLength": 1 }, "maxTokens": { "description": "Maximum output tokens. Runtime must pass this exact value as provider max_tokens or SDK equivalent; zero permits no output.", "type": "string", "pattern": "^(0|[1-9][0-9]{0,11})$", "maxLength": 12, "minLength": 1 }, "images": { "description": "Finite disjoint maximum units; all categories required, explicit zero when unsupported.", "type": "string", "pattern": "^(0|[1-9][0-9]{0,11})$", "maxLength": 12, "minLength": 1 } }, "type": "object", "additionalProperties": false }, "UsageAdmissionDecision": { "required": [ "attemptId", "decision", "reason", "percentageUsed", "resetsAt", "periodKey", "state" ], "properties": { "attemptId": { "type": "string", "format": "uuid" }, "decision": { "type": "string", "enum": [ "allow", "block" ] }, "reason": { "type": "string", "enum": [ "allowed", "not_configured", "disabled", "in_progress", "limit_reached", "usage_unavailable" ] }, "percentageUsed": { "type": "integer", "nullable": true, "maximum": 100, "minimum": 0 }, "resetsAt": { "type": "string", "format": "date-time" }, "periodKey": { "type": "string", "pattern": "^[0-9]{4}-(0[1-9]|1[0-2])$" }, "state": { "required": [ "status", "threshold", "pending" ], "properties": { "status": { "type": "string", "enum": [ "available", "not_configured", "disabled", "in_progress", "limit_reached", "usage_unavailable" ] }, "threshold": { "type": "string", "nullable": true, "enum": [ "below_75", "at_75", "at_95", "at_limit", null ] }, "pending": { "type": "boolean" } }, "type": "object", "additionalProperties": false } }, "type": "object", "additionalProperties": false }, "UsageAdmissionError409": { "required": [ "title", "status", "detail", "error_code" ], "properties": { "title": { "type": "string", "enum": [ "Conflict" ] }, "status": { "type": "integer", "enum": [ 409 ] }, "detail": { "type": "string", "enum": [ "The request conflicts with the original attempt." ] }, "error_code": { "type": "string", "enum": [ "usage_conflict" ] } }, "type": "object", "additionalProperties": false }, "UsageAdmissionError429": { "required": [ "title", "status", "detail", "error_code" ], "properties": { "title": { "type": "string", "enum": [ "Too Many Requests" ] }, "status": { "type": "integer", "enum": [ 429 ] }, "detail": { "type": "string", "enum": [ "Try again later." ] }, "error_code": { "type": "string", "enum": [ "usage_rate_limited" ] } }, "type": "object", "additionalProperties": false }, "UsageBudgetInput": { "oneOf": [ { "required": [ "capMicroUsd" ], "properties": { "capMicroUsd": { "description": "Exact integer micro-USD, maximum 9223372036854775807", "type": "string", "pattern": "^(0|[1-9][0-9]{0,18})$" } }, "type": "object", "additionalProperties": false }, { "required": [ "capUsd" ], "properties": { "capUsd": { "description": "Exact nonnegative USD; submicro loss and overflow rejected", "type": "string", "pattern": "^(0|[1-9][0-9]{0,12})(\\.[0-9]{1,18})?$" } }, "type": "object", "additionalProperties": false } ] }, "UsageBudgetConfiguration": { "required": [ "scope", "personId", "capMicroUsd", "effectiveCapMicroUsd", "source", "state" ], "properties": { "scope": { "type": "string", "enum": [ "company", "person" ] }, "personId": { "type": "string", "nullable": true }, "capMicroUsd": { "type": "string", "nullable": true }, "effectiveCapMicroUsd": { "type": "string", "nullable": true }, "source": { "type": "string", "enum": [ "company", "person", "none" ] }, "state": { "type": "string", "enum": [ "configured", "disabled", "not_configured" ] } }, "type": "object", "additionalProperties": false }, "OwnUsageBudget": { "required": [ "percentageUsed", "resetsAt", "periodKey", "state" ], "properties": { "percentageUsed": { "type": "integer", "nullable": true, "maximum": 100, "minimum": 0 }, "resetsAt": { "type": "string", "format": "date-time" }, "periodKey": { "type": "string", "pattern": "^[0-9]{4}-(0[1-9]|1[0-2])$" }, "state": { "required": [ "status", "threshold", "pending" ], "properties": { "status": { "type": "string", "enum": [ "available", "in_progress", "limit_reached", "not_configured", "disabled" ] }, "threshold": { "type": "string", "nullable": true, "enum": [ "below_75", "at_75", "at_95", "at_limit" ] }, "pending": { "type": "boolean" } }, "type": "object", "additionalProperties": false } }, "type": "object", "additionalProperties": false }, "UsageWarningClaimResult": { "required": [ "notice" ], "properties": { "notice": { "description": "Highest newly claimed threshold notice, or null when there is nothing to show.", "required": [ "claimId", "threshold", "periodKey", "resetsAt" ], "properties": { "claimId": { "type": "string", "format": "uuid" }, "threshold": { "type": "integer", "enum": [ 75, 95 ] }, "periodKey": { "type": "string", "pattern": "^[0-9]{4}-(0[1-9]|1[0-2])$" }, "resetsAt": { "type": "string", "format": "date-time" } }, "type": "object", "nullable": true, "additionalProperties": false } }, "type": "object", "additionalProperties": false }, "UsageBudgetError401": { "required": [ "title", "status", "detail", "error_code" ], "properties": { "title": { "type": "string", "enum": [ "Unauthorized" ] }, "status": { "type": "integer", "enum": [ 401 ] }, "detail": { "type": "string", "enum": [ "Authentication is required." ] }, "error_code": { "type": "string", "enum": [ "usage_unauthenticated" ] } }, "type": "object", "additionalProperties": false }, "UsageBudgetError402": { "oneOf": [ { "required": [ "title", "status", "detail", "error_code" ], "properties": { "title": { "type": "string", "enum": [ "Payment Required" ] }, "status": { "type": "integer", "enum": [ 402 ] }, "detail": { "type": "string", "enum": [ "Debes reportar tu pago para usar el sistema." ] }, "error_code": { "type": "string", "enum": [ "subscription_payment_required" ] } }, "type": "object", "additionalProperties": false }, { "required": [ "title", "status", "detail", "error_code" ], "properties": { "title": { "type": "string", "enum": [ "Payment Required" ] }, "status": { "type": "integer", "enum": [ 402 ] }, "detail": { "type": "string", "enum": [ "Tu suscripción está bloqueada. Contáctanos para recibir ayuda." ] }, "error_code": { "type": "string", "enum": [ "subscription_blocked" ] } }, "type": "object", "additionalProperties": false } ] }, "UsageBudgetError403": { "required": [ "title", "status", "detail", "error_code" ], "properties": { "title": { "type": "string", "enum": [ "Forbidden" ] }, "status": { "type": "integer", "enum": [ 403 ] }, "detail": { "type": "string", "enum": [ "This operation is not permitted." ] }, "error_code": { "type": "string", "enum": [ "usage_forbidden" ] } }, "type": "object", "additionalProperties": false }, "UsageBudgetError404": { "required": [ "title", "status", "detail", "error_code" ], "properties": { "title": { "type": "string", "enum": [ "Not Found" ] }, "status": { "type": "integer", "enum": [ 404 ] }, "detail": { "type": "string", "enum": [ "Resource not found." ] }, "error_code": { "type": "string", "enum": [ "usage_not_found" ] } }, "type": "object", "additionalProperties": false }, "UsageBudgetError422": { "required": [ "title", "status", "detail", "error_code" ], "properties": { "title": { "type": "string", "enum": [ "Unprocessable Entity" ] }, "status": { "type": "integer", "enum": [ 422 ] }, "detail": { "type": "string", "enum": [ "The request is invalid." ] }, "error_code": { "type": "string", "enum": [ "usage_invalid" ] } }, "type": "object", "additionalProperties": false }, "UsageBudgetError503": { "required": [ "title", "status", "detail", "error_code" ], "properties": { "title": { "type": "string", "enum": [ "Service Unavailable" ] }, "status": { "type": "integer", "enum": [ 503 ] }, "detail": { "type": "string", "enum": [ "Usage is temporarily unavailable." ] }, "error_code": { "type": "string", "enum": [ "usage_unavailable" ] } }, "type": "object", "additionalProperties": false }, "UsageBudgetError500": { "required": [ "title", "status", "detail", "error_code" ], "properties": { "title": { "type": "string", "enum": [ "Internal Server Error" ] }, "status": { "type": "integer", "enum": [ 500 ] }, "detail": { "type": "string", "enum": [ "Usage operation could not be completed." ] }, "error_code": { "type": "string", "enum": [ "usage_internal_error" ] } }, "type": "object", "additionalProperties": false }, "AssistantUsageEvent": { "oneOf": [ { "$ref": "#/components/schemas/AssistantUsageCompletionEvent" }, { "$ref": "#/components/schemas/AssistantUsageProvisionalEvent" }, { "$ref": "#/components/schemas/AssistantUsageFinalObservationEvent" }, { "$ref": "#/components/schemas/AssistantUsageNonbillableEvent" } ] }, "AssistantUsageCompletionEvent": { "description": "Confidential-client settlement. Backoffice requires an owned pre-created attempt: personal charges require admission; verified provider retries retain their stored platform charge account. It forbids platformContext. WhatsApp requires trusted Company configuration; platformContext is needed only on first delivery and must match the frozen original if repeated. Advisory costUsd never changes pricing or replay identity.", "required": [ "schemaVersion", "operationId", "attemptId", "kind", "observedAt", "model", "priceVersionId", "usage" ], "properties": { "schemaVersion": { "type": "integer", "enum": [ 1 ] }, "operationId": { "type": "string", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$" }, "attemptId": { "type": "string", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$" }, "kind": { "type": "string", "enum": [ "completion" ] }, "observedAt": { "type": "string", "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,6})?(?:Z|[+-]\\d{2}:\\d{2})$" }, "provenance": { "type": "string", "enum": [ "runtime", "erp", "jev_gateway", "abort" ] }, "generationAlias": { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]*:[^:\\s]+$", "nullable": true, "maxLength": 255 }, "platformContext": { "$ref": "#/components/schemas/AssistantUsagePlatformContext" }, "model": { "type": "string", "maxLength": 128, "minLength": 1 }, "priceVersionId": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "usage": { "$ref": "#/components/schemas/AssistantProviderUsage" }, "decisions": { "description": "Only for owned backoffice-assistant person-actor system_one usage-bearing events with jev_gateway provenance. One to four unique kinds, canonicalized by kind. Changed same-operation or cross-operation metadata conflicts; absence never erases stored decisions.", "type": "array", "items": { "$ref": "#/components/schemas/AssistantUsageDecision" }, "maxItems": 4, "minItems": 1 }, "costUsd": { "description": "Finite advisory telemetry, excluded from exact pricing and canonical replay identity", "type": "number", "minimum": 0 } }, "type": "object", "additionalProperties": false }, "AssistantUsageProvisionalEvent": { "description": "Confidential-client settlement. Backoffice requires an owned pre-created attempt: personal charges require admission; verified provider retries retain their stored platform charge account. It forbids platformContext. WhatsApp requires trusted Company configuration; platformContext is needed only on first delivery and must match the frozen original if repeated. Advisory costUsd never changes pricing or replay identity.", "required": [ "schemaVersion", "operationId", "attemptId", "kind", "observedAt", "model", "priceVersionId", "usage" ], "properties": { "schemaVersion": { "type": "integer", "enum": [ 1 ] }, "operationId": { "type": "string", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$" }, "attemptId": { "type": "string", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$" }, "kind": { "type": "string", "enum": [ "provisional" ] }, "observedAt": { "type": "string", "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,6})?(?:Z|[+-]\\d{2}:\\d{2})$" }, "provenance": { "type": "string", "enum": [ "runtime", "erp", "jev_gateway", "abort" ] }, "generationAlias": { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]*:[^:\\s]+$", "nullable": true, "maxLength": 255 }, "platformContext": { "$ref": "#/components/schemas/AssistantUsagePlatformContext" }, "model": { "type": "string", "maxLength": 128, "minLength": 1 }, "priceVersionId": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "usage": { "$ref": "#/components/schemas/AssistantProviderUsage" }, "decisions": { "description": "Only for owned backoffice-assistant person-actor system_one usage-bearing events with jev_gateway provenance. One to four unique kinds, canonicalized by kind. Changed same-operation or cross-operation metadata conflicts; absence never erases stored decisions.", "type": "array", "items": { "$ref": "#/components/schemas/AssistantUsageDecision" }, "maxItems": 4, "minItems": 1 }, "costUsd": { "description": "Finite advisory telemetry, excluded from exact pricing and canonical replay identity", "type": "number", "minimum": 0 } }, "type": "object", "additionalProperties": false }, "AssistantUsageFinalObservationEvent": { "description": "Confidential-client settlement. Backoffice requires an owned pre-created attempt: personal charges require admission; verified provider retries retain their stored platform charge account. It forbids platformContext. WhatsApp requires trusted Company configuration; platformContext is needed only on first delivery and must match the frozen original if repeated. Advisory costUsd never changes pricing or replay identity.", "required": [ "schemaVersion", "operationId", "attemptId", "kind", "observedAt", "model", "priceVersionId", "usage" ], "properties": { "schemaVersion": { "type": "integer", "enum": [ 1 ] }, "operationId": { "type": "string", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$" }, "attemptId": { "type": "string", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$" }, "kind": { "type": "string", "enum": [ "final_observation" ] }, "observedAt": { "type": "string", "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,6})?(?:Z|[+-]\\d{2}:\\d{2})$" }, "provenance": { "type": "string", "enum": [ "runtime", "erp", "jev_gateway", "abort" ] }, "generationAlias": { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]*:[^:\\s]+$", "nullable": true, "maxLength": 255 }, "platformContext": { "$ref": "#/components/schemas/AssistantUsagePlatformContext" }, "model": { "type": "string", "maxLength": 128, "minLength": 1 }, "priceVersionId": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "usage": { "$ref": "#/components/schemas/AssistantProviderUsage" }, "decisions": { "description": "Only for owned backoffice-assistant person-actor system_one usage-bearing events with jev_gateway provenance. One to four unique kinds, canonicalized by kind. Changed same-operation or cross-operation metadata conflicts; absence never erases stored decisions.", "type": "array", "items": { "$ref": "#/components/schemas/AssistantUsageDecision" }, "maxItems": 4, "minItems": 1 }, "costUsd": { "description": "Finite advisory telemetry, excluded from exact pricing and canonical replay identity", "type": "number", "minimum": 0 } }, "type": "object", "additionalProperties": false }, "AssistantUsageNonbillableEvent": { "description": "Confidential-client settlement. Backoffice requires an owned pre-created attempt: personal charges require admission; verified provider retries retain their stored platform charge account. It forbids platformContext. WhatsApp requires trusted Company configuration; platformContext is needed only on first delivery and must match the frozen original if repeated. Advisory costUsd never changes pricing or replay identity.", "required": [ "schemaVersion", "operationId", "attemptId", "kind", "observedAt", "termination" ], "properties": { "schemaVersion": { "type": "integer", "enum": [ 1 ] }, "operationId": { "type": "string", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$" }, "attemptId": { "type": "string", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$" }, "kind": { "type": "string", "enum": [ "nonbillable" ] }, "observedAt": { "type": "string", "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,6})?(?:Z|[+-]\\d{2}:\\d{2})$" }, "provenance": { "type": "string", "enum": [ "runtime", "erp", "jev_gateway", "abort" ] }, "generationAlias": { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]*:[^:\\s]+$", "nullable": true, "maxLength": 255 }, "platformContext": { "$ref": "#/components/schemas/AssistantUsagePlatformContext" }, "model": { "description": "Required with priceVersionId for a first WhatsApp platform attempt", "type": "string", "maxLength": 128, "minLength": 1 }, "priceVersionId": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "termination": { "type": "string", "enum": [ "provider_rejected_before_dispatch", "verified_no_billable_usage" ] } }, "type": "object", "oneOf": [ { "required": [ "model", "priceVersionId" ] }, { "not": { "anyOf": [ { "required": [ "model" ] }, { "required": [ "priceVersionId" ] } ] } } ], "additionalProperties": false }, "AssistantUsageCount": { "description": "Unsigned decimal whole count at most 9223372036854775807; leading zeros are accepted within 40 characters", "type": "string", "pattern": "^0*(?:[0-9]{1,18}|[0-8][0-9]{18}|9[0-1][0-9]{17}|92[0-1][0-9]{16}|922[0-2][0-9]{15}|9223[0-2][0-9]{14}|92233[0-6][0-9]{13}|922337[0-1][0-9]{12}|92233720[0-2][0-9]{10}|922337203[0-5][0-9]{9}|9223372036[0-7][0-9]{8}|92233720368[0-4][0-9]{7}|922337203685[0-3][0-9]{6}|9223372036854[0-6][0-9]{5}|92233720368547[0-6][0-9]{4}|922337203685477[0-4][0-9]{3}|9223372036854775[0-7][0-9]{2}|922337203685477580[0-6]|9223372036854775807)(?![\\s\\S])", "maxLength": 40, "minLength": 1 }, "AssistantProviderUsage": { "description": "Whole decimal string counts in 0..9223372036854775807; normalization rejects impossible inclusive totals. No double counting of cache, image input or reasoning.", "required": [ "input", "cacheRead", "cacheWrite5m", "cacheWrite1h", "output", "reasoning", "tokenizedImageInput", "images", "inputIncludesCache", "outputIncludesReasoning", "inputIncludesImages" ], "properties": { "input": { "$ref": "#/components/schemas/AssistantUsageCount" }, "cacheRead": { "$ref": "#/components/schemas/AssistantUsageCount" }, "cacheWrite5m": { "$ref": "#/components/schemas/AssistantUsageCount" }, "cacheWrite1h": { "$ref": "#/components/schemas/AssistantUsageCount" }, "output": { "$ref": "#/components/schemas/AssistantUsageCount" }, "reasoning": { "$ref": "#/components/schemas/AssistantUsageCount" }, "tokenizedImageInput": { "$ref": "#/components/schemas/AssistantUsageCount" }, "images": { "$ref": "#/components/schemas/AssistantUsageCount" }, "inputIncludesCache": { "type": "boolean" }, "outputIncludesReasoning": { "type": "boolean" }, "inputIncludesImages": { "type": "boolean" } }, "type": "object", "additionalProperties": false }, "AssistantUsagePlatformContext": { "oneOf": [ { "$ref": "#/components/schemas/AssistantUsageContactContext" }, { "$ref": "#/components/schemas/AssistantUsageSystemContext" } ] }, "AssistantUsageContactContext": { "required": [ "occurredAt", "actor", "bounds", "contactKey" ], "properties": { "retry": { "$ref": "#/components/schemas/AssistantUsageProviderRetry" }, "actor": { "type": "string", "enum": [ "contact" ] }, "occurredAt": { "type": "string", "format": "date-time" }, "bounds": { "$ref": "#/components/schemas/AssistantUsageExecutionBounds" }, "contactKey": { "description": "Opaque contact correlation; never a phone or MCP user", "type": "string", "maxLength": 128, "minLength": 1 } }, "type": "object", "additionalProperties": false }, "AssistantUsageSystemContext": { "required": [ "occurredAt", "actor", "bounds" ], "properties": { "retry": { "$ref": "#/components/schemas/AssistantUsageProviderRetry" }, "actor": { "type": "string", "enum": [ "system" ] }, "occurredAt": { "type": "string", "format": "date-time" }, "bounds": { "$ref": "#/components/schemas/AssistantUsageExecutionBounds" } }, "type": "object", "additionalProperties": false }, "AssistantUsageProviderRetry": { "required": [ "predecessorId", "cause", "evidenceKey" ], "properties": { "predecessorId": { "type": "string", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$" }, "cause": { "type": "string", "enum": [ "provider_unavailable", "provider_rate_limited", "provider_billing_failure" ] }, "evidenceKey": { "description": "Opaque verified technical evidence identity; never provider error text", "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$", "maxLength": 128, "minLength": 1 } }, "type": "object", "additionalProperties": false }, "AssistantUsageExecutionBounds": { "required": [ "input", "cacheWrite5m", "cacheWrite1h", "cacheRead", "maxTokens", "images" ], "properties": { "input": { "$ref": "#/components/schemas/AssistantUsageCount" }, "cacheWrite5m": { "$ref": "#/components/schemas/AssistantUsageCount" }, "cacheWrite1h": { "$ref": "#/components/schemas/AssistantUsageCount" }, "cacheRead": { "$ref": "#/components/schemas/AssistantUsageCount" }, "maxTokens": { "$ref": "#/components/schemas/AssistantUsageCount" }, "images": { "$ref": "#/components/schemas/AssistantUsageCount" } }, "type": "object", "additionalProperties": false }, "AssistantUsageReceipt": { "required": [ "attemptId", "operationId", "result" ], "properties": { "attemptId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" }, "result": { "type": "string", "enum": [ "recorded", "ignored" ] } }, "type": "object", "additionalProperties": false }, "AssistantUsageDecision": { "oneOf": [ { "required": [ "kind", "label", "confidence" ], "properties": { "kind": { "type": "string", "enum": [ "intent" ] }, "label": { "type": "string", "maxLength": 32, "minLength": 1, "enum": [ "help", "data", "navigation", "operation", "support", "out_of_scope" ] }, "confidence": { "type": "string", "pattern": "^(?:0\\.[0-9]{3}|1\\.000)$" }, "modelVersion": { "type": "string", "maxLength": 64, "minLength": 1 } }, "type": "object", "additionalProperties": false }, { "required": [ "kind", "label", "confidence" ], "properties": { "kind": { "type": "string", "enum": [ "model_size" ] }, "label": { "type": "string", "maxLength": 32, "minLength": 1, "enum": [ "small", "medium", "large" ] }, "confidence": { "type": "string", "pattern": "^(?:0\\.[0-9]{3}|1\\.000)$" }, "modelVersion": { "type": "string", "maxLength": 64, "minLength": 1 } }, "type": "object", "additionalProperties": false }, { "required": [ "kind", "label", "confidence" ], "properties": { "kind": { "type": "string", "enum": [ "screening" ] }, "label": { "type": "string", "maxLength": 32, "minLength": 1, "enum": [ "true", "false" ] }, "confidence": { "type": "string", "pattern": "^(?:0\\.[0-9]{3}|1\\.000)$" }, "modelVersion": { "type": "string", "maxLength": 64, "minLength": 1 } }, "type": "object", "additionalProperties": false }, { "required": [ "kind", "label", "confidence" ], "properties": { "kind": { "type": "string", "enum": [ "needs_human" ] }, "label": { "type": "string", "maxLength": 32, "minLength": 1, "enum": [ "true", "false" ] }, "confidence": { "type": "string", "pattern": "^(?:0\\.[0-9]{3}|1\\.000)$" }, "modelVersion": { "type": "string", "maxLength": 64, "minLength": 1 } }, "type": "object", "additionalProperties": false } ] }, "AssistantUsageSpendMoney": { "required": [ "micro_usd", "usd" ], "properties": { "micro_usd": { "description": "Integer micro-USD as a decimal string", "type": "string", "pattern": "^-?[0-9]+$" }, "usd": { "description": "USD at 6 decimal places", "type": "string", "pattern": "^-?[0-9]+\\.[0-9]{6}$" } }, "type": "object", "additionalProperties": false }, "AssistantUsageSpendCacheCoverage": { "required": [ "known_attempts", "total_attempts", "state" ], "properties": { "known_attempts": { "type": "integer", "minimum": 0 }, "total_attempts": { "type": "integer", "minimum": 0 }, "state": { "type": "string", "enum": [ "COMPLETE", "PARTIAL", "NONE" ] } }, "type": "object", "additionalProperties": false }, "AssistantUsageSpendCacheShare": { "required": [ "label", "percent", "coverage" ], "properties": { "label": { "type": "string", "example": "Entrada leída de caché" }, "percent": { "description": "Null when the denominator is zero or metrics are unknown; 0.000000 is a known zero", "type": "string", "pattern": "^[0-9]+\\.[0-9]{6}$", "nullable": true }, "coverage": { "$ref": "#/components/schemas/AssistantUsageSpendCacheCoverage" } }, "type": "object", "additionalProperties": false }, "AssistantUsageSpendReportQuality": { "required": [ "provisional_attempts", "pending_attempts", "unknown_metric_attempts" ], "properties": { "provisional_attempts": { "type": "integer", "minimum": 0 }, "pending_attempts": { "type": "integer", "minimum": 0 }, "unknown_metric_attempts": { "type": "integer", "minimum": 0 } }, "type": "object", "additionalProperties": false }, "AssistantUsageSpendReportTotals": { "required": [ "economic_spend", "pending_reservations", "gateway_debit", "byok_list_estimate", "personal_spend", "platform_spend", "cache_read_share", "quality" ], "properties": { "economic_spend": { "$ref": "#/components/schemas/AssistantUsageSpendMoney" }, "pending_reservations": { "$ref": "#/components/schemas/AssistantUsageSpendMoney" }, "gateway_debit": { "$ref": "#/components/schemas/AssistantUsageSpendMoney" }, "byok_list_estimate": { "$ref": "#/components/schemas/AssistantUsageSpendMoney" }, "personal_spend": { "$ref": "#/components/schemas/AssistantUsageSpendMoney" }, "platform_spend": { "$ref": "#/components/schemas/AssistantUsageSpendMoney" }, "cache_read_share": { "$ref": "#/components/schemas/AssistantUsageSpendCacheShare" }, "quality": { "$ref": "#/components/schemas/AssistantUsageSpendReportQuality" } }, "type": "object", "additionalProperties": false }, "AssistantUsageSpendReportRow": { "required": [ "dimension_key", "label", "allocation", "economic_spend", "cache_read_share_percent" ], "properties": { "dimension_key": { "type": "string" }, "label": { "type": "string" }, "allocation": { "type": "string", "enum": [ "PERSONAL", "PLATFORM" ] }, "economic_spend": { "$ref": "#/components/schemas/AssistantUsageSpendMoney" }, "cache_read_share_percent": { "type": "string", "pattern": "^[0-9]+\\.[0-9]{6}$", "nullable": true } }, "type": "object", "additionalProperties": false }, "AssistantUsageSpendReportFilters": { "required": [ "person_id", "function", "model" ], "properties": { "person_id": { "type": "string", "nullable": true }, "function": { "type": "string", "nullable": true, "enum": [ "in_app", "whatsapp", "receipt_extraction", "system_one", null ] }, "model": { "type": "string", "nullable": true, "maxLength": 128 } }, "type": "object", "additionalProperties": false }, "AssistantUsageSpendReportPagination": { "required": [ "page", "per_page", "total_rows" ], "properties": { "page": { "type": "integer", "minimum": 1 }, "per_page": { "type": "integer", "maximum": 100, "minimum": 1 }, "total_rows": { "type": "integer", "minimum": 0 } }, "type": "object", "additionalProperties": false }, "AssistantUsageSpendReport": { "description": "Company-administrator AI spend report. Distinct from OwnUsageBudget; amounts are economic estimates, not provider invoices.", "required": [ "month", "grouping", "filters", "as_of", "watermark", "pagination", "totals", "rows" ], "properties": { "month": { "type": "string", "pattern": "^[0-9]{4}-(0[1-9]|1[0-2])$" }, "grouping": { "type": "string", "enum": [ "person", "function", "model" ] }, "filters": { "$ref": "#/components/schemas/AssistantUsageSpendReportFilters" }, "as_of": { "type": "string", "format": "date-time" }, "watermark": { "type": "string", "format": "date-time", "nullable": true }, "pagination": { "$ref": "#/components/schemas/AssistantUsageSpendReportPagination" }, "totals": { "$ref": "#/components/schemas/AssistantUsageSpendReportTotals" }, "rows": { "type": "array", "items": { "$ref": "#/components/schemas/AssistantUsageSpendReportRow" } } }, "type": "object", "additionalProperties": false }, "EmailVerificationValidationProblem": { "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string" }, "error_code": { "type": "string", "nullable": true }, "errors": { "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" }, "EmailVerificationAvailabilityProblem": { "required": [ "title", "status", "detail" ], "properties": { "title": { "type": "string", "example": "Service Unavailable" }, "status": { "type": "integer", "example": 503 }, "detail": { "type": "string" } }, "type": "object" }, "EmailVerificationRateLimitProblem": { "required": [ "title", "status", "detail" ], "properties": { "title": { "type": "string", "example": "Too Many Requests" }, "status": { "type": "integer", "example": 429 }, "detail": { "type": "string", "example": "Rate limit exceeded. Please try again later." } }, "type": "object" }, "EmailVerificationMiddlewareError": { "required": [ "message" ], "properties": { "message": { "type": "string", "example": "CSRF token mismatch." } }, "type": "object" }, "AccountingAccountProblem": { "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string", "example": "The given data was invalid." }, "error_code": { "description": "Null for a validation 422; otherwise the domain refusal, such as accounting_hierarchy_cycle.", "type": "string", "example": null, "nullable": true }, "errors": { "description": "Messages keyed by the field or query parameter they refuse (`status.0` for the first value of a list); null when the refusal names no field.", "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" }, "AccountingAccountRow": { "required": [ "id", "code", "name", "description", "type", "status", "parent_id", "creator_id", "updater_id", "company_id", "expense_subtype", "has_children", "parent_code", "parent_name" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "0199a3c1-0000-7000-8000-000000000c61" }, "code": { "type": "string", "example": "6.1.01." }, "name": { "type": "string", "example": "Sueldos y salarios" }, "description": { "type": "string", "example": null, "nullable": true }, "type": { "description": "1 = asset, 2 = liability, 3 = equity, 4 = revenue, 5 = cost, 6 = expense.", "type": "integer", "example": 6, "enum": [ 1, 2, 3, 4, 5, 6 ] }, "status": { "type": "string", "example": "inactive", "enum": [ "active", "inactive" ] }, "parent_id": { "type": "string", "format": "uuid", "example": "0199a3c1-0000-7000-8000-000000000c10", "nullable": true }, "creator_id": { "type": "integer", "example": 7 }, "updater_id": { "type": "integer", "example": 7 }, "company_id": { "type": "string", "format": "uuid", "example": "0199a3c1-0000-7000-8000-00000000c0de" }, "expense_subtype": { "description": "Null unless type is 6, expense.", "type": "string", "example": "operating", "nullable": true, "enum": [ "operating", "tax" ] }, "has_children": { "description": "Whether the company owns a direct subaccount of it: true for a group account («Grupo»), false for a transactional one («Movimiento»).", "type": "boolean", "example": false }, "parent_code": { "description": "Null for a root account, or for a parent outside the company.", "type": "string", "example": "6.1.", "nullable": true }, "parent_name": { "description": "Null for a root account, or for a parent outside the company.", "type": "string", "example": "Gastos de personal", "nullable": true } }, "type": "object" }, "AccountingAccountRecord": { "required": [ "id", "code", "name", "description", "type", "status", "parent_id", "creator_id", "updater_id", "company_id", "expense_subtype", "has_children", "parent_code", "parent_name", "children_count", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "0199a3c1-0000-7000-8000-000000000c61" }, "code": { "type": "string", "example": "6.1." }, "name": { "type": "string", "example": "Gastos de personal" }, "description": { "type": "string", "example": null, "nullable": true }, "type": { "description": "1 = asset, 2 = liability, 3 = equity, 4 = revenue, 5 = cost, 6 = expense.", "type": "integer", "example": 6, "enum": [ 1, 2, 3, 4, 5, 6 ] }, "status": { "type": "string", "example": "active", "enum": [ "active", "inactive" ] }, "parent_id": { "type": "string", "format": "uuid", "example": "0199a3c1-0000-7000-8000-000000000c10", "nullable": true }, "creator_id": { "type": "integer", "example": 7 }, "updater_id": { "type": "integer", "example": 7 }, "company_id": { "type": "string", "format": "uuid", "example": "0199a3c1-0000-7000-8000-00000000c0de" }, "expense_subtype": { "description": "Null unless type is 6, expense.", "type": "string", "example": "operating", "nullable": true, "enum": [ "operating", "tax" ] }, "has_children": { "description": "Whether children_count is above zero: true for a group account («Grupo»), false for a transactional one («Movimiento»).", "type": "boolean", "example": true }, "parent_code": { "description": "Null for a root account, or for a parent outside the company.", "type": "string", "example": "6.", "nullable": true }, "parent_name": { "description": "Null for a root account, or for a parent outside the company.", "type": "string", "example": "Gastos", "nullable": true }, "children_count": { "description": "Direct subaccounts the company owns under this account.", "type": "integer", "example": 2, "minimum": 0 }, "created_at": { "description": "UTC instant the account was created; null for a legacy row that never recorded it.", "type": "string", "format": "date-time", "example": "2026-10-01T12:00:00+00:00", "nullable": true }, "updated_at": { "description": "UTC instant the account was last updated; null for a legacy row that never recorded it.", "type": "string", "format": "date-time", "example": "2026-10-02T08:30:05+00:00", "nullable": true } }, "type": "object" }, "AccountingAccountsListMeta": { "required": [ "counts", "type_counts" ], "properties": { "counts": { "description": "Matching accounts by status under every filter but status, zero-filled.", "required": [ "active", "inactive" ], "properties": { "active": { "type": "integer", "example": 41 }, "inactive": { "type": "integer", "example": 3 } }, "type": "object" }, "type_counts": { "description": "Matching accounts by type under every filter but type, zero-filled.", "required": [ "1", "2", "3", "4", "5", "6" ], "properties": { "1": { "type": "integer", "example": 0 }, "2": { "type": "integer", "example": 0 }, "3": { "type": "integer", "example": 0 }, "4": { "type": "integer", "example": 0 }, "5": { "type": "integer", "example": 0 }, "6": { "type": "integer", "example": 3 } }, "type": "object" } }, "type": "object" }, "AccountingAccountsPage": { "required": [ "items", "total", "per_page", "current_page", "meta" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AccountingAccountRow" } }, "total": { "type": "integer", "example": 3 }, "per_page": { "type": "integer", "example": 50 }, "current_page": { "type": "integer", "example": 1 }, "meta": { "$ref": "#/components/schemas/AccountingAccountsListMeta" } }, "type": "object" }, "AccountingAccountImportFileUnreadableProblem": { "description": "A chart-of-accounts upload refuses a file it cannot open as a workbook (MER-5094).", "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string", "example": "Bad Request" }, "status": { "type": "integer", "example": 400 }, "detail": { "type": "string", "example": "No se pudo leer el archivo. Verifica que sea un Excel (.xlsx o .xls) válido." }, "error_code": { "type": "string", "enum": [ "accounting_account_import_file_unreadable" ] }, "errors": { "description": "Always null.", "type": "object", "nullable": true } }, "type": "object" }, "AccountingAccountImportColumnsMismatchProblem": { "description": "A chart-of-accounts upload refuses a file whose first row is not the template header (MER-5094).", "required": [ "title", "status", "detail", "error_code", "errors", "expected_columns", "optional_columns" ], "properties": { "title": { "type": "string", "example": "Bad Request" }, "status": { "type": "integer", "example": 400 }, "detail": { "type": "string", "example": "El archivo debe tener las columnas: Código, Nombre, Tipo, Descripción" }, "error_code": { "type": "string", "enum": [ "accounting_account_import_columns_mismatch" ] }, "errors": { "description": "Always null.", "type": "object", "nullable": true }, "expected_columns": { "description": "The headers the first row must start with, in order, as the template writes them.", "type": "array", "items": { "type": "string", "example": "Código" }, "example": [ "Código", "Nombre", "Tipo", "Descripción" ] }, "optional_columns": { "description": "The headers that may follow them, in order, as the template writes them.", "type": "array", "items": { "type": "string", "example": "Rol contable" }, "example": [ "Rol contable", "Subtipo gasto" ] } }, "type": "object" }, "AccountingAccountImportTooManyRowsProblem": { "description": "A chart-of-accounts upload refuses a file with more rows than one import takes (MER-5094).", "required": [ "title", "status", "detail", "error_code", "errors", "max_rows" ], "properties": { "title": { "type": "string", "example": "Bad Request" }, "status": { "type": "integer", "example": 400 }, "detail": { "type": "string", "example": "El archivo excede el límite de 1000 filas" }, "error_code": { "type": "string", "enum": [ "accounting_account_import_too_many_rows" ] }, "errors": { "description": "Always null.", "type": "object", "nullable": true }, "max_rows": { "description": "The most rows below the header one import takes.", "type": "integer", "example": 1000, "minimum": 1 } }, "type": "object" }, "AccountingAccountImportFileEmptyProblem": { "description": "A chart-of-accounts upload refuses a file with no account below its header (MER-5094).", "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string", "example": "Bad Request" }, "status": { "type": "integer", "example": 400 }, "detail": { "type": "string", "example": "El archivo no contiene datos válidos" }, "error_code": { "type": "string", "enum": [ "accounting_account_import_file_empty" ] }, "errors": { "description": "Always null.", "type": "object", "nullable": true } }, "type": "object" }, "AccountingAccountImportRequiredCellMissingProblem": { "description": "A chart-of-accounts upload refuses a row whose code, name or type is blank or holds only spaces (MER-5094).", "required": [ "title", "status", "detail", "error_code", "errors", "row", "column" ], "properties": { "title": { "type": "string", "example": "Bad Request" }, "status": { "type": "integer", "example": 400 }, "detail": { "type": "string", "example": "Fila 3: El nombre es obligatorio" }, "error_code": { "type": "string", "enum": [ "accounting_account_import_required_cell_missing" ] }, "errors": { "description": "Always null.", "type": "object", "nullable": true }, "row": { "description": "The workbook row, counting the header as row 1.", "type": "integer", "example": 3, "minimum": 2 }, "column": { "description": "The blank cell: the code, name or type column («Código», «Nombre», «Tipo»).", "type": "string", "example": "name", "enum": [ "code", "name", "type" ] } }, "type": "object" }, "AccountingAccountImportTypeNotRecognizedProblem": { "description": "A chart-of-accounts upload refuses a row whose type is not one of the six labels (MER-4876).", "required": [ "title", "status", "detail", "error_code", "errors", "row", "refused_type", "allowed_types" ], "properties": { "title": { "type": "string", "example": "Bad Request" }, "status": { "type": "integer", "example": 400 }, "detail": { "type": "string", "example": "Fila 2: El tipo 'Activos' no es válido; debe ser uno de: Activo, Pasivo, Patrimonio, Ingreso, Costo, Gasto" }, "error_code": { "type": "string", "enum": [ "accounting_account_import_type_not_recognized" ] }, "errors": { "description": "Always null.", "type": "object", "nullable": true }, "row": { "description": "The workbook row that holds the type, counting the header as row 1; null when the refusal names no row.", "type": "integer", "example": 2, "nullable": true, "minimum": 2 }, "refused_type": { "description": "The type cell as the file wrote it, trimmed of spaces and non-breaking spaces. Not `type`, which RFC 9457 reserves for the problem type URI.", "type": "string", "example": "Activos" }, "allowed_types": { "description": "The six labels the type column accepts, in chart order.", "type": "array", "items": { "type": "string", "example": "Activo" }, "example": [ "Activo", "Pasivo", "Patrimonio", "Ingreso", "Costo", "Gasto" ] } }, "type": "object" }, "AccountingAccountImportCodeMalformedProblem": { "description": "A chart-of-accounts upload refuses a row whose code is not numbers separated by dots (MER-5094).", "required": [ "title", "status", "detail", "error_code", "errors", "row", "refused_code" ], "properties": { "title": { "type": "string", "example": "Bad Request" }, "status": { "type": "integer", "example": 400 }, "detail": { "type": "string", "example": "Fila 2: El código '1-1' no tiene un formato válido (ej: 1., 1.1., 1.1.01.)" }, "error_code": { "type": "string", "enum": [ "accounting_account_import_code_malformed" ] }, "errors": { "description": "Always null.", "type": "object", "nullable": true }, "row": { "description": "The workbook row, counting the header as row 1.", "type": "integer", "example": 2, "minimum": 2 }, "refused_code": { "description": "The code cell as the file wrote it, trimmed of spaces and non-breaking spaces.", "type": "string", "example": "1-1" } }, "type": "object" }, "AccountingAccountImportRoleNotAllowedProblem": { "description": "A chart-of-accounts upload refuses a row whose role is not an Account Purpose its type takes, or no Account Purpose at all (MER-5094).", "required": [ "title", "status", "detail", "error_code", "errors", "row", "refused_role", "account_type" ], "properties": { "title": { "type": "string", "example": "Bad Request" }, "status": { "type": "integer", "example": 400 }, "detail": { "type": "string", "example": "Fila 4: El rol contable 'receivable' no es válido para este tipo de cuenta" }, "error_code": { "type": "string", "enum": [ "accounting_account_import_role_not_allowed" ] }, "errors": { "description": "Always null.", "type": "object", "nullable": true }, "row": { "description": "The workbook row, counting the header as row 1.", "type": "integer", "example": 4, "minimum": 2 }, "refused_role": { "description": "The role cell as the file wrote it: a raw Account Purpose value, or text that names none.", "type": "string", "example": "receivable" }, "account_type": { "description": "The row's type label, one of the six.", "type": "string", "example": "Pasivo" } }, "type": "object" }, "AccountingAccountImportRoleRepeatedProblem": { "description": "A chart-of-accounts upload refuses a row whose role an earlier row of the file already took (MER-5094).", "required": [ "title", "status", "detail", "error_code", "errors", "row", "refused_role" ], "properties": { "title": { "type": "string", "example": "Bad Request" }, "status": { "type": "integer", "example": 400 }, "detail": { "type": "string", "example": "Fila 7: El rol contable 'payable' está repetido" }, "error_code": { "type": "string", "enum": [ "accounting_account_import_role_repeated" ] }, "errors": { "description": "Always null.", "type": "object", "nullable": true }, "row": { "description": "The workbook row that repeats the role, counting the header as row 1.", "type": "integer", "example": 7, "minimum": 2 }, "refused_role": { "description": "The repeated Account Purpose value, as the file wrote it.", "type": "string", "example": "payable" } }, "type": "object" }, "AccountingAccountImportRoleRequiresLeafAccountProblem": { "description": "A chart-of-accounts upload refuses a role on an account the file also brings subaccounts of (MER-5094).", "required": [ "title", "status", "detail", "error_code", "errors", "account_code", "refused_role" ], "properties": { "title": { "type": "string", "example": "Bad Request" }, "status": { "type": "integer", "example": 400 }, "detail": { "type": "string", "example": "El rol contable 'receivable' requiere una cuenta hoja" }, "error_code": { "type": "string", "enum": [ "accounting_account_import_role_requires_leaf_account" ] }, "errors": { "description": "Always null.", "type": "object", "nullable": true }, "account_code": { "description": "The code of the account that carries the role and has subaccounts in the file.", "type": "string", "example": "1.2." }, "refused_role": { "description": "The Account Purpose value the file gives it.", "type": "string", "example": "receivable" } }, "type": "object" }, "AccountingAccountImportExpenseSubtypeNotAllowedProblem": { "description": "A chart-of-accounts upload refuses a row whose expense subtype its type does not take (MER-5094).", "required": [ "title", "status", "detail", "error_code", "errors", "row", "refused_subtype", "account_type", "allowed_subtypes" ], "properties": { "title": { "type": "string", "example": "Bad Request" }, "status": { "type": "integer", "example": 400 }, "detail": { "type": "string", "example": "Fila 9: Subtipo gasto inválido" }, "error_code": { "type": "string", "enum": [ "accounting_account_import_expense_subtype_not_allowed" ] }, "errors": { "description": "Always null.", "type": "object", "nullable": true }, "row": { "description": "The workbook row, counting the header as row 1.", "type": "integer", "example": 9, "minimum": 2 }, "refused_subtype": { "description": "The expense subtype cell as the file wrote it.", "type": "string", "example": "admin" }, "account_type": { "description": "The row's type label, one of the six.", "type": "string", "example": "Gasto" }, "allowed_subtypes": { "description": "The subtypes the row's type takes; empty when it takes none, as every type but Gasto.", "type": "array", "items": { "type": "string", "example": "operating" }, "example": [ "operating", "tax" ] } }, "type": "object" }, "AccountingAccountCodeAlreadyExistsProblem": { "description": "A chart-of-accounts upload refuses a file that repeats codes or brings codes the company already holds, before any write (MER-4876). Exactly one of codes_repeated_in_file and codes_already_in_chart is non-empty; the repeated codes are checked first (MER-5094).", "required": [ "title", "status", "detail", "error_code", "errors", "account_code", "codes_repeated_in_file", "codes_already_in_chart" ], "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "detail": { "type": "string", "example": "El código de cuenta contable <1.1.03.> ya existe en el sistema" }, "error_code": { "type": "string", "enum": [ "accounting_account_code_already_exists" ] }, "errors": { "description": "Always null.", "type": "object", "nullable": true }, "account_code": { "description": "The first refused code: the first of codes_repeated_in_file, or else the first of codes_already_in_chart.", "type": "string", "example": "1.1.03." }, "codes_repeated_in_file": { "description": "Every code the file repeats, once each, in the order the file repeats them; empty when the refusal is codes_already_in_chart.", "type": "array", "items": { "type": "string", "example": "1.1.03." }, "example": [] }, "codes_already_in_chart": { "description": "Every code of the file the company already holds, in file order (up to the 1000 rows a file may bring); empty when the refusal is codes_repeated_in_file.", "type": "array", "items": { "type": "string", "example": "1.1.03." }, "example": [ "1.1.03." ] } }, "type": "object" }, "AccountingCenterProblem": { "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "detail": { "type": "string", "example": "Ya existe un centro contable con el id 0199e1a2-0000-7000-8000-000000000060" }, "error_code": { "description": "Null for a validation 422 or a 403; otherwise the domain refusal, such as accounting_center_already_exists, accounting_center_not_found, accounting_center_hierarchy_cycle or accounting_center_parent_not_found.", "type": "string", "example": "accounting_center_already_exists", "nullable": true }, "errors": { "description": "Messages keyed by the field or query parameter they refuse (`status.0` for the first value of a list); null when the refusal names no field.", "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" }, "AccountingCenter": { "required": [ "id", "code", "name", "description", "status", "parentId", "creatorId", "updaterId", "responsibleUserId", "companyId", "responsibleUserName", "parentCode", "parentName", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "0199e1a2-0000-7000-8000-000000000060" }, "code": { "type": "string", "example": "ADM" }, "name": { "type": "string", "example": "Administración" }, "description": { "type": "string", "example": "Gastos generales", "nullable": true }, "status": { "type": "string", "example": "active", "enum": [ "active", "inactive" ] }, "parentId": { "type": "string", "format": "uuid", "example": null, "nullable": true }, "creatorId": { "type": "integer", "example": 7 }, "updaterId": { "type": "integer", "example": 9 }, "responsibleUserId": { "description": "The Responsable; the creator for a legacy center that never stored one.", "type": "integer", "example": 41 }, "companyId": { "type": "string", "format": "uuid", "example": "0199a3c1-0000-7000-8000-00000000c0de" }, "responsibleUserName": { "description": "The Responsable's name while that user is a member of the company; null otherwise, never an id.", "type": "string", "example": "Ana Pérez", "nullable": true }, "parentCode": { "description": "Null for a root center, or for a parent outside the company.", "type": "string", "example": null, "nullable": true }, "parentName": { "description": "Null for a root center, or for a parent outside the company.", "type": "string", "example": null, "nullable": true }, "createdAt": { "description": "UTC instant the center was created; null for a legacy row that never recorded it.", "type": "string", "format": "date-time", "example": "2026-09-21T14:03:11+00:00", "nullable": true }, "updatedAt": { "description": "UTC instant the center was last updated; null for a legacy row that never recorded it.", "type": "string", "format": "date-time", "example": "2026-10-14T14:03:11+00:00", "nullable": true } }, "type": "object" }, "AccountingCentersListMeta": { "required": [ "counts" ], "properties": { "counts": { "description": "Matching centers by status under every filter but status, zero-filled.", "required": [ "active", "inactive" ], "properties": { "active": { "type": "integer", "example": 1 }, "inactive": { "type": "integer", "example": 0 } }, "type": "object" } }, "type": "object" }, "AccountingCentersPage": { "required": [ "items", "total", "per_page", "current_page", "meta" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AccountingCenter" } }, "total": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 20 }, "current_page": { "type": "integer", "example": 1 }, "meta": { "$ref": "#/components/schemas/AccountingCentersListMeta" } }, "type": "object" }, "AccountingPeriod": { "description": "One calendar month of the company's ledger. A month on or before the closed-through month is closed whether or not it was closed by itself, so it may show no closer. Who closed a month and when show only while the month itself stays closed; who reopened it, when and why show as last recorded.", "required": [ "period", "status", "closed_at", "closed_by", "reopened_at", "reopened_by", "reopen_reason" ], "properties": { "period": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$", "example": "2026-08" }, "status": { "type": "string", "example": "closed", "enum": [ "open", "closed" ] }, "closed_at": { "type": "string", "format": "date-time", "example": "2026-09-15T15:00:00+00:00", "nullable": true }, "closed_by": { "description": "The user who closed the month; null while the month is open or when it was closed with an earlier one.", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "example": "42" }, "name": { "description": "Null when the user no longer exists.", "type": "string", "example": "Ana Contadora", "nullable": true } }, "type": "object", "nullable": true }, "reopened_at": { "type": "string", "format": "date-time", "example": null, "nullable": true }, "reopened_by": { "description": "The user who last reopened the month; null when it was never reopened.", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "example": "11" }, "name": { "description": "Null when the user no longer exists.", "type": "string", "example": "Luis Auditor", "nullable": true } }, "type": "object", "nullable": true }, "reopen_reason": { "type": "string", "example": null, "nullable": true } }, "type": "object" }, "FxRevaluationProposeResult": { "required": [ "drafts" ], "properties": { "drafts": { "type": "array", "items": { "required": [ "id", "group" ], "properties": { "id": { "type": "string", "format": "uuid" }, "group": { "type": "string", "enum": [ "treasury", "control" ] } }, "type": "object" } } }, "type": "object" }, "FxRevaluationPreview": { "required": [ "month", "month_end", "closing_rate", "treasury", "control" ], "properties": { "month": { "type": "string", "example": "2026-09" }, "month_end": { "type": "string", "format": "date", "example": "2026-09-30" }, "closing_rate": { "required": [ "rate", "value_date", "pair" ], "properties": { "rate": { "type": "string", "example": "140.00000000" }, "value_date": { "type": "string", "format": "date", "example": "2026-09-30" }, "pair": { "type": "string", "example": "USD/VES" } }, "type": "object", "nullable": true }, "treasury": { "type": "array", "items": { "$ref": "#/components/schemas/FxRevaluationPreviewLine" } }, "control": { "type": "array", "items": { "$ref": "#/components/schemas/FxRevaluationPreviewLine" } } }, "type": "object" }, "FxRevaluationPreviewLine": { "required": [ "accounting_account_id", "accounting_center_id", "original_currency", "units", "functional_balance", "target_functional", "difference", "side", "counterpart_role", "counterpart_account_id", "counterpart_center_id" ], "properties": { "accounting_account_id": { "type": "string", "format": "uuid" }, "accounting_center_id": { "type": "string", "format": "uuid" }, "original_currency": { "type": "string", "example": "USD" }, "units": { "type": "string", "example": "292.88" }, "functional_balance": { "type": "string", "example": "29288.00" }, "target_functional": { "type": "string", "example": "41003.20" }, "difference": { "type": "string", "example": "11715.20" }, "side": { "type": "string", "enum": [ "debit", "credit" ] }, "counterpart_role": { "type": "string", "example": "unrealized_exchange_gain" }, "counterpart_account_id": { "type": "string", "format": "uuid" }, "counterpart_center_id": { "type": "string", "format": "uuid" } }, "type": "object" }, "FxRevaluationProblem": { "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string" }, "error_code": { "type": "string", "example": "month_not_ended", "nullable": true }, "errors": { "type": "object", "nullable": true }, "position": { "description": "1-based proposal line for ManualEntryLineRefusal (MER-4548)", "type": "integer", "example": 1, "minimum": 1 }, "book": { "description": "Present on some ManualEntryLineRefusal amounts; functional or reporting", "type": "string", "enum": [ "functional", "reporting" ] }, "currencies": { "description": "Present for closing_rate_unavailable", "type": "array", "items": { "type": "string" } }, "role": { "description": "Present for posting_account_role_missing", "type": "string" }, "draft_id": { "description": "Present for fx_revaluation_draft_pending", "type": "string", "format": "uuid" }, "month": { "description": "Present for fx_revaluation_draft_pending", "type": "string" } }, "type": "object" }, "IncomeStatementRow": { "required": [ "account_id", "parent_id", "original_parent_id", "code", "name", "type", "level", "is_group", "amount" ], "properties": { "account_id": { "type": "string", "format": "uuid" }, "parent_id": { "type": "string", "format": "uuid", "nullable": true }, "original_parent_id": { "type": "string", "format": "uuid", "nullable": true }, "code": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "integer", "enum": [ 4, 5, 6 ] }, "level": { "type": "integer", "minimum": 0 }, "is_group": { "type": "boolean" }, "amount": { "$ref": "#/components/schemas/LedgerReportAmount" } }, "type": "object" }, "IncomeStatementTotals": { "description": "Direct revenue, costs and expenses counted once; signed net result equals revenue minus costs minus expenses", "required": [ "revenue", "costs", "expenses", "net_result" ], "properties": { "revenue": { "$ref": "#/components/schemas/LedgerReportAmount" }, "costs": { "$ref": "#/components/schemas/LedgerReportAmount" }, "expenses": { "$ref": "#/components/schemas/LedgerReportAmount" }, "net_result": { "$ref": "#/components/schemas/LedgerReportAmount" } }, "type": "object" }, "IncomeStatement": { "required": [ "range", "book", "currency_code", "accounting_center_id", "rows", "totals" ], "properties": { "range": { "required": [ "from", "to" ], "properties": { "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" } }, "type": "object" }, "book": { "type": "string", "enum": [ "functional", "reporting" ] }, "currency_code": { "type": "string" }, "accounting_center_id": { "type": "string", "format": "uuid", "nullable": true }, "rows": { "description": "Category-specific authoritative preorder; signed subtree amounts include parent direct postings", "type": "array", "items": { "$ref": "#/components/schemas/IncomeStatementRow" } }, "totals": { "$ref": "#/components/schemas/IncomeStatementTotals" } }, "type": "object" }, "BalanceSheetRow": { "required": [ "account_id", "parent_id", "original_parent_id", "code", "name", "type", "level", "is_group", "amount" ], "properties": { "account_id": { "type": "string", "format": "uuid" }, "parent_id": { "type": "string", "format": "uuid", "nullable": true }, "original_parent_id": { "type": "string", "format": "uuid", "nullable": true }, "code": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "integer", "enum": [ 1, 2, 3 ] }, "level": { "type": "integer", "minimum": 0 }, "is_group": { "type": "boolean" }, "amount": { "$ref": "#/components/schemas/LedgerReportAmount" } }, "type": "object" }, "BalanceSheetTotals": { "description": "Direct facts counted once; posted equity excludes cumulative Unclosed Result; all signs preserved", "required": [ "assets", "liabilities", "equity", "unclosed_result", "difference" ], "properties": { "assets": { "$ref": "#/components/schemas/LedgerReportAmount" }, "liabilities": { "$ref": "#/components/schemas/LedgerReportAmount" }, "equity": { "$ref": "#/components/schemas/LedgerReportAmount" }, "unclosed_result": { "$ref": "#/components/schemas/LedgerReportAmount" }, "difference": { "$ref": "#/components/schemas/LedgerReportAmount" } }, "type": "object" }, "BalanceSheet": { "required": [ "date", "book", "currency_code", "accounting_center_id", "rows", "totals" ], "properties": { "date": { "type": "string", "format": "date" }, "book": { "type": "string", "enum": [ "functional", "reporting" ] }, "currency_code": { "type": "string" }, "accounting_center_id": { "type": "string", "format": "uuid", "nullable": true }, "rows": { "description": "Category-specific authoritative preorder; signed subtree amounts include parent direct postings", "type": "array", "items": { "$ref": "#/components/schemas/BalanceSheetRow" } }, "totals": { "$ref": "#/components/schemas/BalanceSheetTotals" } }, "type": "object" }, "GeneralLedgerAccount": { "required": [ "id", "code", "name", "type", "status", "is_group", "nature" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "integer", "enum": [ 1, 2, 3, 4, 5, 6 ] }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "is_group": { "description": "Derived from the full effective company catalog before movement filtering", "type": "boolean" }, "nature": { "description": "Selected root nature: debit for types 1/5/6, credit for 2/3/4; applies to algebraic child facts", "type": "string", "enum": [ "debit", "credit" ] } }, "type": "object" }, "GeneralLedgerDetailRow": { "required": [ "id", "date", "transaction_id", "transaction_code", "transaction_type", "account_id", "account_code", "account_name", "accounting_center_id", "accounting_center_code", "accounting_center_name", "debit", "credit", "running_balance", "linkable_type", "linkable_id", "document_code", "source_document_available" ], "properties": { "id": { "type": "string", "format": "uuid" }, "date": { "description": "Stored transaction item date; header date does not control selection or chronology", "type": "string", "format": "date" }, "transaction_id": { "type": "string", "format": "uuid" }, "transaction_code": { "type": "string" }, "transaction_type": { "type": "string" }, "account_id": { "type": "string", "format": "uuid" }, "account_code": { "type": "string" }, "account_name": { "type": "string" }, "accounting_center_id": { "description": "Stored financial center ID is retained when optional display metadata is missing or foreign", "type": "string", "format": "uuid" }, "accounting_center_code": { "type": "string", "nullable": true }, "accounting_center_name": { "type": "string", "nullable": true }, "debit": { "description": "Exact nonnegative posted amount in selected book", "type": "string", "pattern": "^[0-9]+[.][0-9]{2}$" }, "credit": { "description": "Exact nonnegative posted amount in selected book", "type": "string", "pattern": "^[0-9]+[.][0-9]{2}$" }, "running_balance": { "$ref": "#/components/schemas/LedgerReportAmount" }, "linkable_type": { "description": "Recorded open source alias, including unknown historical aliases", "type": "string" }, "linkable_id": { "description": "Recorded opaque source ID; unusable IDs remain visible and unavailable", "type": "string" }, "document_code": { "description": "Correct company/kind source code when available. Opening balances and treasury transfers have no code column.", "type": "string", "nullable": true }, "source_document_available": { "description": "Recognized usable source ID exists for this company and kind at the response snapshot. Does not assert document authorization. Existing opening/transfer returns true with null code; missing/foreign/wrong-kind/unknown/unusable source returns false.", "type": "boolean" } }, "type": "object" }, "GeneralLedgerDetailPagination": { "required": [ "current_page", "per_page", "total", "last_page", "from", "to", "previous_page", "next_page", "is_out_of_range" ], "properties": { "current_page": { "type": "integer", "maximum": 2147483647, "minimum": 1 }, "per_page": { "type": "integer", "enum": [ 200 ] }, "total": { "description": "Complete selected-period line count", "type": "integer", "minimum": 0 }, "last_page": { "description": "max(1,ceil(total/200))", "type": "integer", "minimum": 1 }, "from": { "description": "One-based first line position, null when empty or out of range", "type": "integer", "nullable": true, "minimum": 1 }, "to": { "type": "integer", "nullable": true, "minimum": 1 }, "previous_page": { "description": "min(current_page-1,last_page) when current_page exceeds 1", "type": "integer", "nullable": true, "minimum": 1 }, "next_page": { "description": "Null on last or overflow page", "type": "integer", "nullable": true, "minimum": 1 }, "is_out_of_range": { "description": "current_page > last_page; normal empty page 1 remains false", "type": "boolean" } }, "type": "object" }, "GeneralLedgerDetail": { "required": [ "range", "book", "currency_code", "account_id", "include_subtree", "accounting_center_id", "account", "opening_balance", "page_opening_balance", "page_closing_balance", "closing_balance", "totals", "rows", "pagination" ], "properties": { "range": { "required": [ "from", "to" ], "properties": { "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" } }, "type": "object" }, "book": { "type": "string", "enum": [ "functional", "reporting" ] }, "currency_code": { "description": "Company's stored currency for selected book; no FX conversion", "type": "string" }, "account_id": { "type": "string", "format": "uuid" }, "include_subtree": { "type": "boolean" }, "accounting_center_id": { "type": "string", "format": "uuid", "nullable": true }, "account": { "$ref": "#/components/schemas/GeneralLedgerAccount" }, "opening_balance": { "description": "Root-natural opening from all selected postings before from, including actual openings/reversals", "allOf": [ { "$ref": "#/components/schemas/LedgerReportAmount" } ] }, "page_opening_balance": { "description": "Opening plus every preceding period movement, root-natural; full closing on overflow", "allOf": [ { "$ref": "#/components/schemas/LedgerReportAmount" } ] }, "page_closing_balance": { "$ref": "#/components/schemas/LedgerReportAmount" }, "closing_balance": { "description": "Complete selected range closing, independent of page", "allOf": [ { "$ref": "#/components/schemas/LedgerReportAmount" } ] }, "totals": { "description": "Complete selected period, never page-only totals", "required": [ "debits", "credits" ], "properties": { "debits": { "type": "string", "pattern": "^[0-9]+[.][0-9]{2}$" }, "credits": { "type": "string", "pattern": "^[0-9]+[.][0-9]{2}$" } }, "type": "object" }, "rows": { "description": "Stable item-date/entry-code/item-ID chronology; missing optional metadata never removes financial lines", "type": "array", "items": { "$ref": "#/components/schemas/GeneralLedgerDetailRow" }, "maxItems": 200 }, "pagination": { "$ref": "#/components/schemas/GeneralLedgerDetailPagination" } }, "type": "object" }, "LedgerReportTooLargeProblem": { "required": [ "title", "status", "detail", "error_code", "errors", "line_count", "max_lines" ], "properties": { "title": { "type": "string", "enum": [ "Unprocessable Entity" ] }, "status": { "type": "integer", "enum": [ 422 ] }, "detail": { "type": "string" }, "error_code": { "type": "string", "enum": [ "ledger_report_too_large" ] }, "errors": { "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "line_count": { "description": "Exact complete selected-period count before loading/enriching export lines", "type": "integer", "minimum": 10001 }, "max_lines": { "type": "integer", "enum": [ 10000 ] } }, "type": "object" }, "JournalLine": { "required": [ "id", "date", "account_id", "account_code", "account_name", "accounting_center_id", "accounting_center_code", "accounting_center_name", "debit", "credit" ], "properties": { "id": { "type": "string", "format": "uuid" }, "date": { "description": "Stored line date controls financial membership", "type": "string", "format": "date" }, "account_id": { "type": "string", "format": "uuid" }, "account_code": { "type": "string" }, "account_name": { "type": "string" }, "accounting_center_id": { "description": "Stored ID retained even when optional catalog metadata is unavailable or foreign", "type": "string", "format": "uuid" }, "accounting_center_code": { "type": "string", "nullable": true }, "accounting_center_name": { "type": "string", "nullable": true }, "debit": { "type": "string", "pattern": "^[0-9]+[.][0-9]{2}$" }, "credit": { "type": "string", "pattern": "^[0-9]+[.][0-9]{2}$" } }, "type": "object" }, "JournalEntry": { "required": [ "id", "date", "code", "type", "linkable_type", "linkable_id", "document_code", "source_document_available", "totals", "lines" ], "properties": { "id": { "type": "string", "format": "uuid" }, "date": { "description": "Authentic header date used for ordering; may be outside selected line-date range", "type": "string", "format": "date" }, "code": { "type": "string" }, "type": { "description": "Open historical transaction type", "type": "string" }, "linkable_type": { "description": "Recorded open source alias", "type": "string" }, "linkable_id": { "description": "Opaque historical source ID", "type": "string" }, "document_code": { "type": "string", "nullable": true }, "source_document_available": { "description": "Company/kind source availability in snapshot; no assertion of document authorization. Treasury/opening sources may be available with null code.", "type": "boolean" }, "totals": { "description": "Exact selected-line totals; partial selections need not balance", "required": [ "debits", "credits" ], "properties": { "debits": { "type": "string", "pattern": "^[0-9]+[.][0-9]{2}$" }, "credits": { "type": "string", "pattern": "^[0-9]+[.][0-9]{2}$" } }, "type": "object" }, "lines": { "description": "Every selected line for this header, ordered by line date and ID, without clipping", "type": "array", "items": { "$ref": "#/components/schemas/JournalLine" }, "minItems": 1 } }, "type": "object" }, "JournalPagination": { "required": [ "current_page", "per_page", "total", "last_page", "from", "to", "previous_page", "next_page", "is_out_of_range" ], "properties": { "current_page": { "type": "integer", "maximum": 2147483647, "minimum": 1 }, "per_page": { "type": "integer", "enum": [ 50 ] }, "total": { "description": "Distinct headers across complete selection", "type": "integer", "minimum": 0 }, "last_page": { "description": "max(1,ceil(total/50))", "type": "integer", "minimum": 1 }, "from": { "type": "integer", "nullable": true, "minimum": 1 }, "to": { "type": "integer", "nullable": true, "minimum": 1 }, "previous_page": { "description": "min(page-1,last_page) when page exceeds 1", "type": "integer", "nullable": true, "minimum": 1 }, "next_page": { "type": "integer", "nullable": true, "minimum": 1 }, "is_out_of_range": { "description": "Requested page exceeds last page; normal empty page 1 is false", "type": "boolean" } }, "type": "object" }, "Journal": { "required": [ "range", "book", "currency_code", "accounting_center_id", "line_count", "totals", "entries", "pagination" ], "properties": { "range": { "required": [ "from", "to" ], "properties": { "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" } }, "type": "object" }, "book": { "type": "string", "enum": [ "functional", "reporting" ] }, "currency_code": { "type": "string" }, "accounting_center_id": { "type": "string", "format": "uuid", "nullable": true }, "line_count": { "description": "Complete selected-range line count, independent of page", "type": "integer", "minimum": 0 }, "totals": { "description": "Exact selected-line totals; partial selections need not balance", "required": [ "debits", "credits" ], "properties": { "debits": { "type": "string", "pattern": "^[0-9]+[.][0-9]{2}$" }, "credits": { "type": "string", "pattern": "^[0-9]+[.][0-9]{2}$" } }, "type": "object" }, "entries": { "description": "50-header page in authentic header date/code/ID chronology. Empty and overflow return empty entries with full summary.", "type": "array", "items": { "$ref": "#/components/schemas/JournalEntry" }, "maxItems": 50 }, "pagination": { "$ref": "#/components/schemas/JournalPagination" } }, "type": "object" }, "LedgerReportAmount": { "type": "string", "pattern": "^-?[0-9]+[.][0-9]{2}$", "example": "120.00" }, "LedgerReportMessageError": { "required": [ "message" ], "properties": { "message": { "type": "string" } }, "type": "object" }, "LedgerReportValidationError": { "required": [ "message", "errors" ], "properties": { "message": { "type": "string" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" }, "LedgerReportForbiddenError": { "required": [ "title", "status", "detail" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "reason": { "type": "string" } }, "type": "object" }, "LedgerReportProblem": { "required": [ "title", "status", "detail", "error_code" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "error_code": { "type": "string", "nullable": true }, "errors": { "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" }, "TrialBalanceRow": { "required": [ "account_id", "parent_id", "original_parent_id", "code", "name", "type", "level", "is_group", "opening_balance", "debits", "credits", "closing_balance" ], "properties": { "account_id": { "type": "string", "format": "uuid" }, "parent_id": { "type": "string", "format": "uuid", "nullable": true }, "original_parent_id": { "type": "string", "format": "uuid", "nullable": true }, "code": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "integer", "enum": [ 1, 2, 3, 4, 5, 6 ] }, "level": { "type": "integer", "minimum": 0 }, "is_group": { "type": "boolean" }, "opening_balance": { "$ref": "#/components/schemas/LedgerReportAmount" }, "debits": { "$ref": "#/components/schemas/LedgerReportAmount" }, "credits": { "$ref": "#/components/schemas/LedgerReportAmount" }, "closing_balance": { "$ref": "#/components/schemas/LedgerReportAmount" } }, "type": "object" }, "TrialBalanceTotals": { "description": "Direct facts counted once; opening and closing are algebraic. Period net result is unclamped and excludes opening.", "required": [ "opening_balance", "debits", "credits", "closing_balance", "difference", "net_result" ], "properties": { "opening_balance": { "$ref": "#/components/schemas/LedgerReportAmount" }, "debits": { "$ref": "#/components/schemas/LedgerReportAmount" }, "credits": { "$ref": "#/components/schemas/LedgerReportAmount" }, "closing_balance": { "$ref": "#/components/schemas/LedgerReportAmount" }, "difference": { "$ref": "#/components/schemas/LedgerReportAmount" }, "net_result": { "$ref": "#/components/schemas/LedgerReportAmount" } }, "type": "object" }, "TrialBalance": { "required": [ "range", "book", "currency_code", "accounting_center_id", "include_zero", "rows", "totals" ], "properties": { "range": { "required": [ "from", "to" ], "properties": { "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" } }, "type": "object" }, "book": { "type": "string", "enum": [ "functional", "reporting" ] }, "currency_code": { "type": "string" }, "accounting_center_id": { "type": "string", "format": "uuid", "nullable": true }, "include_zero": { "type": "boolean" }, "rows": { "description": "Authoritative preorder; natural-signed subtree balances; effective hierarchy normalized for cycles and orphans", "type": "array", "items": { "$ref": "#/components/schemas/TrialBalanceRow" } }, "totals": { "$ref": "#/components/schemas/TrialBalanceTotals" } }, "type": "object" }, "ManualEntryLineInput": { "description": "One line of a manual entry: the amount it states in its original currency and the amounts captured for each book. A book kept in the original currency posts the original amount, and when both books keep one currency they post the same amount. A line moves at least one book; an amount may be 0, for instance a revaluation that moves only the functional book.", "required": [ "accounting_account_id", "accounting_center_id", "side", "original_currency", "original_amount", "functional_amount", "reporting_amount" ], "properties": { "accounting_account_id": { "description": "An active accounting account of the company.", "type": "string", "format": "uuid" }, "accounting_center_id": { "description": "An active accounting center of the company.", "type": "string", "format": "uuid" }, "side": { "type": "string", "enum": [ "debit", "credit" ] }, "original_currency": { "type": "string", "enum": [ "USD", "VES", "USDT", "EUR", "DOP" ] }, "original_amount": { "description": "Decimal string, zero or more, with at most 2 decimals.", "type": "string", "pattern": "^\\d{1,13}(\\.\\d{1,2})?$", "example": "100.00" }, "functional_amount": { "description": "Decimal string, zero or more, with at most 2 decimals, in the company's functional currency.", "type": "string", "pattern": "^\\d{1,13}(\\.\\d{1,2})?$", "example": "100.00" }, "reporting_amount": { "description": "Decimal string, zero or more, with at most 2 decimals, in the company's reporting currency.", "type": "string", "pattern": "^\\d{1,13}(\\.\\d{1,2})?$", "example": "0.27" }, "memo": { "description": "Optional; blank is stored as null.", "type": "string", "example": "Banco VES", "nullable": true, "maxLength": 255 } }, "type": "object", "additionalProperties": false }, "ManualEntryReviseRequest": { "required": [ "date", "purpose", "description", "source_reference", "lines" ], "properties": { "date": { "description": "The accounting date; not after the company's today.", "type": "string", "format": "date", "example": "2026-09-24" }, "purpose": { "type": "string", "enum": [ "adjustment", "provision", "reclassification", "fx_revaluation", "tax_settlement" ] }, "description": { "type": "string", "example": "Comisiones bancarias del 24/09", "maxLength": 500 }, "source_reference": { "description": "The supporting document.", "type": "string", "example": "Extracto 24/09", "maxLength": 255 }, "policy_reference": { "description": "The policy the entry applies. Required when `purpose` is fx_revaluation; blank is stored as null.", "type": "string", "example": null, "nullable": true, "maxLength": 255 }, "reverse_on": { "description": "Optional Scheduled Reversal date, YYYY-MM-DD: any day of the calendar month after `date`, otherwise 422 manual_entry_reverse_on_out_of_range. When set, approval also posts `manual_entry.reversed` on that day and the entry may leave a receivable or payable control account moved. Null or omitted: no reversal; a revision without it removes it.", "type": "string", "format": "date", "example": "2026-10-01", "nullable": true }, "lines": { "description": "In the order they are listed; GET numbers them 1..n.", "type": "array", "items": { "$ref": "#/components/schemas/ManualEntryLineInput" }, "maxItems": 500, "minItems": 2 } }, "type": "object" }, "ManualEntryRegisterRequest": { "allOf": [ { "$ref": "#/components/schemas/ManualEntryReviseRequest" }, { "required": [ "id" ], "properties": { "id": { "description": "Generated by the client; resending it with the same terms answers the entry as it stands.", "type": "string", "format": "uuid", "example": "0199b6c2-5a1e-7c3d-9f00-2b8f0e6a1c11" } }, "type": "object" } ] }, "ManualEntryCancelRequest": { "required": [ "reason" ], "properties": { "reason": { "description": "Why the entry is cancelled. Surrounding whitespace is trimmed first and the 1 to 500 characters are counted on what remains, so no raw maximum length is published; inner line breaks are kept and a blank reason is refused (422 errors.reason).", "type": "string", "example": "Duplicado del AM2600003", "minLength": 1 } }, "type": "object" }, "ManualEntryWriteResult": { "description": "The written entry's identity and status; read the full entry with GET.", "required": [ "id", "code", "status" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string", "example": "AM2600001" }, "status": { "type": "string", "enum": [ "draft", "approved", "cancelled" ] } }, "type": "object" }, "ManualEntryLine": { "required": [ "id", "position", "accounting_account_id", "accounting_center_id", "side", "original_currency", "original_amount", "functional_amount", "reporting_amount", "memo" ], "properties": { "id": { "type": "string", "format": "uuid" }, "position": { "description": "1-based, in the order the lines were listed; a line refusal names it.", "type": "integer", "minimum": 1 }, "accounting_account_id": { "type": "string", "format": "uuid" }, "accounting_center_id": { "type": "string", "format": "uuid" }, "side": { "type": "string", "enum": [ "debit", "credit" ] }, "original_currency": { "type": "string", "enum": [ "USD", "VES", "USDT", "EUR", "DOP" ] }, "original_amount": { "type": "string", "example": "100.00" }, "functional_amount": { "type": "string", "example": "100.00" }, "reporting_amount": { "type": "string", "example": "0.27" }, "memo": { "type": "string", "example": "Banco VES", "nullable": true } }, "type": "object" }, "ManualEntryActor": { "required": [ "id", "name" ], "properties": { "id": { "type": "string", "example": "42" }, "name": { "description": "Null when the user no longer exists.", "type": "string", "example": "Ana Contadora", "nullable": true } }, "type": "object" }, "ManualEntryLedgerEntry": { "description": "A ledger entry the manual entry posted.", "required": [ "id", "code", "type", "date" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "type": { "description": "`manual_entry.approved`, `manual_entry.reversed` (its Scheduled Reversal) or `manual_entry.cancelled`.", "type": "string", "example": "manual_entry.approved" }, "date": { "type": "string", "format": "date", "example": "2026-09-24" } }, "type": "object" }, "ManualEntrySummary": { "description": "A manual entry as the list shows it, with its totals per book.", "required": [ "id", "code", "date", "purpose", "description", "source_reference", "policy_reference", "status", "line_count", "totals", "created_by", "created_at", "approved_by", "approved_at", "reverse_on", "cancelled_by", "cancelled_at", "cancel_reason" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "description": "`AM`, the year's two digits and a five-digit sequence the year restarts.", "type": "string", "example": "AM2600001" }, "date": { "type": "string", "format": "date", "example": "2026-09-24" }, "purpose": { "type": "string", "enum": [ "adjustment", "provision", "reclassification", "fx_revaluation", "tax_settlement" ] }, "description": { "type": "string" }, "source_reference": { "type": "string" }, "policy_reference": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "draft", "approved", "cancelled" ] }, "line_count": { "type": "integer", "example": 2 }, "totals": { "description": "Debit and credit totals of each book; an approved entry's are equal in each book.", "required": [ "functional", "reporting" ], "properties": { "functional": { "required": [ "debit", "credit" ], "properties": { "debit": { "type": "string", "example": "100.00" }, "credit": { "type": "string", "example": "100.00" } }, "type": "object" }, "reporting": { "required": [ "debit", "credit" ], "properties": { "debit": { "type": "string", "example": "0.27" }, "credit": { "type": "string", "example": "0.27" } }, "type": "object" } }, "type": "object" }, "created_by": { "$ref": "#/components/schemas/ManualEntryActor" }, "created_at": { "type": "string", "format": "date-time", "example": "2026-09-24T15:00:00+00:00" }, "approved_by": { "description": "The user who approved the entry; null while it is a draft.", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "example": "11" }, "name": { "description": "Null when the user no longer exists.", "type": "string", "example": "Luis Auditor", "nullable": true } }, "type": "object", "nullable": true }, "approved_at": { "type": "string", "format": "date-time", "example": "2026-09-24T15:05:00+00:00", "nullable": true }, "reverse_on": { "description": "The day its Scheduled Reversal undoes it on; null when it schedules none.", "type": "string", "format": "date", "example": "2026-10-01", "nullable": true }, "cancelled_by": { "description": "The user who cancelled the entry; null unless cancelled.", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "example": "42" }, "name": { "description": "Null when the user no longer exists.", "type": "string", "example": "Ana Contadora", "nullable": true } }, "type": "object", "nullable": true }, "cancelled_at": { "type": "string", "format": "date-time", "example": "2026-09-26T15:00:00+00:00", "nullable": true }, "cancel_reason": { "description": "Why it was cancelled; null unless cancelled.", "type": "string", "example": "Duplicado del AM2600003", "nullable": true } }, "type": "object" }, "ManualEntry": { "allOf": [ { "$ref": "#/components/schemas/ManualEntrySummary" }, { "required": [ "lines", "transactions" ], "properties": { "lines": { "type": "array", "items": { "$ref": "#/components/schemas/ManualEntryLine" } }, "transactions": { "description": "The ledger entries it posted, oldest first; empty for a draft.", "type": "array", "items": { "$ref": "#/components/schemas/ManualEntryLedgerEntry" } } }, "type": "object" } ] }, "ManualEntryProblem": { "description": "A refusal: `title`, `status`, `detail`, `error_code` (null for a validation error) and `errors`, the offending request fields. Some business rules add their own members: `position` (1-based) and, on manual_entry_line_amount_mismatch and manual_entry_line_rate_out_of_range, `book` for a line refusal, whose `errors` key is the 0-based request path such as `lines.0.functional_amount`; `functional_difference`, `reporting_difference` (debit total minus credit total, signed, 2 decimals) and `unbalanced_books` on manual_entry_unbalanced; `account_ids` (sorted) on manual_entry_control_account_not_neutral. An approval dated in a closed accounting period answers `{error: accounting_configuration_incomplete, missing[]}` instead.", "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string" }, "error_code": { "type": "string", "example": "manual_entry_unbalanced", "nullable": true }, "errors": { "description": "The offending request fields, each with its messages.", "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "position": { "type": "integer", "example": 1, "minimum": 1 }, "book": { "type": "string", "enum": [ "functional", "reporting" ] }, "functional_difference": { "type": "string", "example": "0.01" }, "reporting_difference": { "type": "string", "example": "0.00" }, "unbalanced_books": { "type": "array", "items": { "type": "string", "enum": [ "functional", "reporting" ] } }, "account_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "error": { "type": "string", "enum": [ "accounting_configuration_incomplete" ] }, "missing": { "type": "array", "items": { "required": [ "reason_code", "subject_type", "subject_id", "human_message", "details" ], "properties": { "reason_code": { "type": "string", "example": "ACCOUNTING_PERIOD_CLOSED" }, "subject_type": { "type": "string", "example": "company" }, "subject_id": { "type": "string", "format": "uuid" }, "human_message": { "type": "string" }, "details": { "type": "array", "items": { "type": "string" }, "example": [ "2026-08", "2026-08-20" ] } }, "type": "object" } } }, "type": "object" }, "CloseFindingItem": { "description": "One record a finding points at. The client links it from its type and id, and from its date for a withholding; the API sends no route. A check may add the record's date, counterparty and amount; an absent one is omitted.", "required": [ "type", "id", "label" ], "properties": { "type": { "description": "An open set: later checks add types, so a client shows an unknown type without a link.", "type": "string", "example": "purchases_invoice", "enum": [ "sales_invoice", "sales_credit_note", "sales_debit_note", "purchases_invoice", "purchases_credit_note", "purchases_debit_note", "manual_entry", "accounting_period", "official_rate_date", "client", "provider", "customer_advance", "supplier_advance", "vat_withholding", "islr_withholding", "fiscal_period", "sales_book_ledger_check", "purchase_book_ledger_check", "bank_reconciliation", "treasury_account", "accounting_account", "accounting_account_reporting_book" ] }, "id": { "description": "The record's id; the month, YYYY-MM, for an accounting_period; the day, YYYY-MM-DD, for an official_rate_date; the period key, YYYY-MM, YYYY-MM-1 or YYYY-MM-2, for a fiscal_period; the month, YYYY-MM, for a sales_book_ledger_check or a purchase_book_ledger_check, whose label names the book and, for a difference without cause, its scope (two items of the Purchase Book may share their type and id); the treasury account's id for a bank_reconciliation (that account's Bank Reconciliation of the close's month, which may not exist yet; several items may share it) or a treasury_account; the accounting account's id for an accounting_account (read in the functional book) or an accounting_account_reporting_book (read in the reporting book); several items may share it.", "type": "string", "example": "0199a000-0000-7000-8000-0000000000f1" }, "label": { "description": "What the record is known by, such as a document's code; the statement line's note for an item of UNIDENTIFIED_STATEMENT_LINES; the code and the words of its purpose, or Propósito sin indicar, for an item of ADVANCE_WITHOUT_SERVICE.", "type": "string", "example": "FC-0001" }, "date": { "description": "The day the record is dated on, such as an advance's origin day, a withholding's trigger date or a statement line's operation day.", "type": "string", "format": "date", "example": "2026-09-15" }, "counterparty": { "description": "The name of the record's client or provider, when known, or the treasury account's name for a statement line in transit.", "type": "string", "example": "Cliente E" }, "amount": { "description": "The record's amount, such as an advance's open balance or, for ADVANCE_WITHOUT_SERVICE, the amount it collected, the signed sum a book ledger check scope leaves without cause, a statement line's signed amount, an account's signed debit − credit units in their original currency for REVALUATION_DUE or expected − actual in the book's currency for OPEN_BALANCE_DIFFERENCES, as a decimal string; present together with currency.", "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "1160.00" }, "currency": { "description": "The ISO code of amount; present together with amount.", "type": "string", "example": "VES" } }, "type": "object" }, "CloseFinding": { "description": "One answer of the month-end close checklist (ADR 0269). A check that finds nothing answers no finding.", "required": [ "code", "severity", "count", "items", "message" ], "properties": { "code": { "description": "What the finding reports; an open set that later checks extend, such as ACCOUNTING_PERIOD_ALREADY_CLOSED, DOCUMENTS_PENDING_APPROVAL, FISCAL_PERIOD_NOT_FROZEN, BOOK_LEDGER_UNEXPLAINED, BANK_RECONCILIATION_OPEN, BANK_RECONCILIATION_DRIFT, WITHHOLDING_NOT_CERTIFIED, RATE_GAPS, COUNTERPARTY_IDENTITY_INCOMPLETE, UNAPPLIED_CASH, ADVANCE_WITHOUT_SERVICE, BOOK_LEDGER_UNAVAILABLE, UNIDENTIFIED_STATEMENT_LINES, TREASURY_ACCOUNTS_NOT_RECONCILABLE, REVALUATION_POSTED, OPEN_BALANCE_DIFFERENCES or REVALUATION_DUE.", "type": "string", "pattern": "^[A-Z][A-Z0-9_]{0,63}$", "example": "DOCUMENTS_PENDING_APPROVAL" }, "severity": { "description": "A blocking finding refuses the close, a warning closes only with a justification, an informative one only informs.", "type": "string", "example": "blocking", "enum": [ "blocking", "warning", "info" ] }, "count": { "description": "How many records the check found; items lists at most the first 100.", "type": "integer", "example": 1, "minimum": 1 }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/CloseFindingItem" }, "maxItems": 100 }, "message": { "description": "The sentence the user reads, in Spanish.", "type": "string", "example": "Hay 1 documento o asiento manual por aprobar con fecha en 2026-09." } }, "type": "object" }, "MonthEndCloseJustification": { "required": [ "code", "text" ], "properties": { "code": { "description": "The warning it justifies.", "type": "string", "pattern": "^[A-Z][A-Z0-9_]{0,63}$", "example": "TEST_WARNING" }, "text": { "type": "string", "example": "Anticipo documentado en el expediente 12.", "maxLength": 500, "minLength": 1 } }, "type": "object" }, "MonthEndClose": { "description": "One stored month-end close: the findings its checklist answered at the close, the justification of each warning, the month's fiscal periods it closed, who closed the month and when.", "required": [ "id", "month", "findings", "justifications", "closed_fiscal_periods", "closed_by", "closed_at", "reopened" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "0199a000-0000-7000-8000-0000000000e1" }, "month": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$", "example": "2026-09" }, "findings": { "description": "In checklist order; [] when nothing was found.", "type": "array", "items": { "$ref": "#/components/schemas/CloseFinding" } }, "justifications": { "description": "One per warning, in findings order; [] when no warning stood.", "type": "array", "items": { "$ref": "#/components/schemas/MonthEndCloseJustification" } }, "closed_fiscal_periods": { "description": "The month's fiscal periods the close closed from in review, oldest first: the month alone (YYYY-MM) or its fortnights (YYYY-MM-1, YYYY-MM-2). [] when it closed none, including a company without a configured fiscal profile and a close stored before fiscal periods joined the close.", "type": "array", "items": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])(-[12])?$", "example": "2026-09-2" } }, "closed_by": { "required": [ "id", "name" ], "properties": { "id": { "type": "string", "example": "42" }, "name": { "description": "Null when the user no longer exists.", "type": "string", "example": "Ana Contadora", "nullable": true } }, "type": "object" }, "closed_at": { "type": "string", "format": "date-time", "example": "2026-10-05T15:00:00+00:00" }, "reopened": { "description": "True when the month's accounting period was reopened after this close, undoing it.", "type": "boolean", "example": false } }, "type": "object" }, "OpeningDocumentGroup": { "required": [ "document_type", "accounting_account_id", "accounting_account_code", "accounting_account_name", "document_currency", "pending_original_amount", "functional_currency", "functional_carrying_amount", "reporting_currency", "reporting_carrying_amount", "document_count" ], "properties": { "document_type": { "type": "string", "enum": [ "sales", "purchase" ] }, "accounting_account_id": { "type": "string", "format": "uuid" }, "accounting_account_code": { "description": "Null only when historical account metadata is unavailable", "type": "string", "nullable": true }, "accounting_account_name": { "type": "string", "nullable": true }, "document_currency": { "type": "string" }, "pending_original_amount": { "type": "string", "pattern": "^[0-9]+[.][0-9]{2}$", "example": "1000.00" }, "functional_currency": { "type": "string" }, "functional_carrying_amount": { "type": "string", "pattern": "^[0-9]+[.][0-9]{2}$", "example": "1000.00" }, "reporting_currency": { "type": "string" }, "reporting_carrying_amount": { "type": "string", "pattern": "^[0-9]+[.][0-9]{2}$", "example": "10.00" }, "document_count": { "type": "integer", "minimum": 0 } }, "type": "object" }, "OpeningBalanceRowError": { "required": [ "row", "message" ], "properties": { "row": { "type": "integer", "minimum": 0 }, "message": { "type": "string" } }, "type": "object" }, "OpeningBalanceReportData": { "required": [ "id", "opening_date", "opening_account_id", "functional_currency", "reporting_currency", "balanced_functional", "functional_debit_total", "functional_credit_total", "functional_difference", "functional_short_side", "reporting_debit_total", "reporting_credit_total", "reporting_residue", "reporting_residue_side", "row_errors", "applied", "transaction_code", "notes", "line_count", "document_count", "document_groups", "reconciliation_available" ], "properties": { "id": { "type": "string", "format": "uuid" }, "opening_date": { "type": "string", "format": "date" }, "opening_account_id": { "type": "string", "format": "uuid" }, "functional_currency": { "type": "string" }, "reporting_currency": { "type": "string" }, "balanced_functional": { "type": "boolean" }, "functional_debit_total": { "type": "string", "pattern": "^[0-9]+[.][0-9]{2}$" }, "functional_credit_total": { "type": "string", "pattern": "^[0-9]+[.][0-9]{2}$" }, "functional_difference": { "type": "string", "pattern": "^[0-9]+[.][0-9]{2}$" }, "functional_short_side": { "type": "string", "nullable": true, "enum": [ "debit", "credit", null ] }, "reporting_debit_total": { "type": "string", "pattern": "^[0-9]+[.][0-9]{2}$" }, "reporting_credit_total": { "type": "string", "pattern": "^[0-9]+[.][0-9]{2}$" }, "reporting_residue": { "type": "string", "pattern": "^[0-9]+[.][0-9]{2}$" }, "reporting_residue_side": { "type": "string", "nullable": true, "enum": [ "debit", "credit", null ] }, "row_errors": { "type": "array", "items": { "$ref": "#/components/schemas/OpeningBalanceRowError" } }, "applied": { "type": "boolean" }, "transaction_code": { "type": "string", "nullable": true }, "notes": { "type": "array", "items": { "type": "string" } }, "line_count": { "description": "Valid Saldos rows; null for an unavailable legacy draft", "type": "integer", "nullable": true, "minimum": 0 }, "document_count": { "description": "Valid Documentos rows; zero is an available empty sheet", "type": "integer", "nullable": true, "minimum": 0 }, "document_groups": { "type": "array", "items": { "$ref": "#/components/schemas/OpeningDocumentGroup" } }, "reconciliation_available": { "type": "boolean" } }, "type": "object" }, "OpeningBalanceReport": { "allOf": [ { "$ref": "#/components/schemas/OpeningBalanceReportData" }, { "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "draft", "confirmed", "reversed" ] } }, "type": "object" } ] }, "OpeningBalanceConfirmationProblem": { "allOf": [ { "$ref": "#/components/schemas/OpeningBalanceReportData" }, { "required": [ "title", "status", "opening_status", "detail", "error_code" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer", "enum": [ 422 ] }, "opening_status": { "type": "string", "enum": [ "draft" ] }, "detail": { "type": "string" }, "error_code": { "type": "string", "enum": [ "opening_balance_row_errors", "opening_balance_unbalanced" ] } }, "type": "object" } ] }, "OpeningBalanceProblem": { "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "error_code": { "type": "string", "nullable": true }, "errors": { "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" }, "OpeningBalanceMiddlewareProblem": { "required": [ "title", "status", "detail" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "reason": { "description": "Present when tenant role membership is refused", "type": "string" } }, "type": "object" }, "OpeningBalanceMessageError": { "required": [ "message" ], "properties": { "message": { "type": "string" }, "status": { "type": "string", "enum": [ "email_not_verified" ] }, "detail": { "type": "string" } }, "type": "object" }, "AccountingSettingsProblem": { "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string", "example": "La tasa del impuesto <0199e1a2-0000-7000-8000-000000000071> no se puede cambiar porque uno o más documentos la usan" }, "error_code": { "description": "Null for a validation 422 or a 403; otherwise the domain refusal, such as tax_already_exists or tax_rate_immutable_after_document_reference. The frontend words its copy from this code.", "type": "string", "example": "tax_rate_immutable_after_document_reference", "nullable": true }, "errors": { "description": "Messages keyed by the field they refuse. A domain refusal of one field repeats its message under that field; null when the refusal names no field.", "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" }, "AccountingSettingsStatusCounts": { "description": "Matching rows by status under every filter but status, zero-filled.", "required": [ "active", "inactive" ], "properties": { "active": { "type": "integer", "example": 2, "minimum": 0 }, "inactive": { "type": "integer", "example": 1, "minimum": 0 } }, "type": "object" }, "AccountingSettingsStatusListMeta": { "required": [ "counts" ], "properties": { "counts": { "$ref": "#/components/schemas/AccountingSettingsStatusCounts" } }, "type": "object" }, "Tax": { "required": [ "id", "name", "description", "rate", "kind", "status", "accounting_account_id", "company_id", "accounting_center_id", "account_code", "account_name", "center_code", "center_name" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "0199e1a2-0000-7000-8000-000000000071" }, "name": { "type": "string", "example": "IVA General" }, "description": { "type": "string", "example": "Impuesto al valor agregado", "nullable": true }, "rate": { "description": "A percentage with two decimals.", "type": "string", "example": "16.00" }, "kind": { "type": "string", "example": "vat_general", "enum": [ "vat_general", "vat_reduced", "vat_additional", "exempt", "exonerated", "not_subject", "export", "other" ] }, "is_default_purchase": { "type": "boolean" }, "is_default_sales": { "type": "boolean" }, "status": { "type": "string", "example": "active", "enum": [ "active", "inactive" ] }, "accounting_account_id": { "type": "string", "format": "uuid", "example": "0199e1a2-0000-7000-8000-000000000072" }, "company_id": { "type": "string", "format": "uuid", "example": "0199a3c1-0000-7000-8000-00000000c0de" }, "accounting_center_id": { "description": "The accounting center's id, or null when the tax has none.", "type": "string", "format": "uuid", "example": "0199e1a2-0000-7000-8000-000000000073", "nullable": true }, "account_code": { "description": "Null when the account does not resolve in the company.", "type": "string", "example": "2.1.03.", "nullable": true }, "account_name": { "description": "Null when the account does not resolve in the company.", "type": "string", "example": "IVA por pagar", "nullable": true }, "center_code": { "description": "Null when the tax has no center or it does not resolve in the company.", "type": "string", "example": "ADM", "nullable": true }, "center_name": { "description": "Null when the tax has no center or it does not resolve in the company.", "type": "string", "example": "Administración", "nullable": true } }, "type": "object" }, "TaxesPage": { "required": [ "items", "total", "per_page", "current_page", "meta" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Tax" } }, "total": { "type": "integer", "example": 1, "minimum": 0 }, "per_page": { "type": "integer", "example": 20 }, "current_page": { "type": "integer", "example": 1 }, "meta": { "$ref": "#/components/schemas/AccountingSettingsStatusListMeta" } }, "type": "object" }, "AccountingSettingsDefaultCounts": { "description": "Matching rows that are the company's default and the others, under every filter but default.", "required": [ "default", "other" ], "properties": { "default": { "type": "integer", "example": 1, "minimum": 0 }, "other": { "type": "integer", "example": 2, "minimum": 0 } }, "type": "object" }, "AccountingSettingsDefaultListMeta": { "required": [ "counts" ], "properties": { "counts": { "$ref": "#/components/schemas/AccountingSettingsDefaultCounts" } }, "type": "object" }, "PayableAccount": { "required": [ "id", "default", "accounting_account_payable_id", "accounting_center_payable_id", "company_id", "account_code", "account_name", "center_code", "center_name" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "0199e1a2-0000-7000-8000-000000000081" }, "default": { "description": "Whether this is the company's default payable account.", "type": "boolean", "example": true }, "accounting_account_payable_id": { "type": "string", "format": "uuid", "example": "0199e1a2-0000-7000-8000-000000000082" }, "accounting_center_payable_id": { "type": "string", "format": "uuid", "example": "0199e1a2-0000-7000-8000-000000000083" }, "company_id": { "type": "string", "format": "uuid", "example": "0199a3c1-0000-7000-8000-00000000c0de" }, "account_code": { "description": "Null when the account does not resolve in the company.", "type": "string", "example": "2.1.01.", "nullable": true }, "account_name": { "description": "Null when the account does not resolve in the company.", "type": "string", "example": "Proveedores nacionales", "nullable": true }, "center_code": { "description": "Null when the center does not resolve in the company.", "type": "string", "example": "ADM", "nullable": true }, "center_name": { "description": "Null when the center does not resolve in the company.", "type": "string", "example": "Administración", "nullable": true } }, "type": "object" }, "PayableAccountsPage": { "required": [ "items", "total", "per_page", "current_page", "meta" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/PayableAccount" } }, "total": { "type": "integer", "example": 1, "minimum": 0 }, "per_page": { "type": "integer", "example": 20 }, "current_page": { "type": "integer", "example": 1 }, "meta": { "$ref": "#/components/schemas/AccountingSettingsDefaultListMeta" } }, "type": "object" }, "ReceivableAccount": { "required": [ "id", "default", "accounting_account_receivable_id", "accounting_center_receivable_id", "company_id", "account_code", "account_name", "center_code", "center_name" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "0199e1a2-0000-7000-8000-000000000091" }, "default": { "description": "Whether this is the company's default receivable account.", "type": "boolean", "example": true }, "accounting_account_receivable_id": { "type": "string", "format": "uuid", "example": "0199e1a2-0000-7000-8000-000000000092" }, "accounting_center_receivable_id": { "type": "string", "format": "uuid", "example": "0199e1a2-0000-7000-8000-000000000093" }, "company_id": { "type": "string", "format": "uuid", "example": "0199a3c1-0000-7000-8000-00000000c0de" }, "account_code": { "description": "Null when the account does not resolve in the company.", "type": "string", "example": "1.1.03.", "nullable": true }, "account_name": { "description": "Null when the account does not resolve in the company.", "type": "string", "example": "Clientes nacionales", "nullable": true }, "center_code": { "description": "Null when the center does not resolve in the company.", "type": "string", "example": "ADM", "nullable": true }, "center_name": { "description": "Null when the center does not resolve in the company.", "type": "string", "example": "Administración", "nullable": true } }, "type": "object" }, "ReceivableAccountsPage": { "required": [ "items", "total", "per_page", "current_page", "meta" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ReceivableAccount" } }, "total": { "type": "integer", "example": 1, "minimum": 0 }, "per_page": { "type": "integer", "example": 20 }, "current_page": { "type": "integer", "example": 1 }, "meta": { "$ref": "#/components/schemas/AccountingSettingsDefaultListMeta" } }, "type": "object" }, "InventoryInTransitAccount": { "required": [ "id", "account_id", "center_id", "status", "type", "company_id", "account_code", "account_name", "center_code", "center_name" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "0199e1a2-0000-7000-8000-0000000000a1" }, "account_id": { "type": "string", "format": "uuid", "example": "0199e1a2-0000-7000-8000-0000000000a2" }, "center_id": { "type": "string", "format": "uuid", "example": "0199e1a2-0000-7000-8000-0000000000a3" }, "status": { "type": "string", "example": "active", "enum": [ "active", "inactive" ] }, "type": { "type": "string", "example": "ASSET", "enum": [ "ASSET", "LIABILITY" ] }, "company_id": { "type": "string", "format": "uuid", "example": "0199a3c1-0000-7000-8000-00000000c0de" }, "account_code": { "description": "Null when the account does not resolve in the company.", "type": "string", "example": "1.1.07.", "nullable": true }, "account_name": { "description": "Null when the account does not resolve in the company.", "type": "string", "example": "Mercancía en tránsito", "nullable": true }, "center_code": { "description": "Null when the center does not resolve in the company.", "type": "string", "example": "ADM", "nullable": true }, "center_name": { "description": "Null when the center does not resolve in the company.", "type": "string", "example": "Administración", "nullable": true } }, "type": "object" }, "InventoryInTransitAccountsPage": { "required": [ "items", "total", "per_page", "current_page", "meta" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/InventoryInTransitAccount" } }, "total": { "type": "integer", "example": 1, "minimum": 0 }, "per_page": { "type": "integer", "example": 20 }, "current_page": { "type": "integer", "example": 1 }, "meta": { "$ref": "#/components/schemas/AccountingSettingsStatusListMeta" } }, "type": "object" }, "VatInputAccountWarning": { "description": "A non-blocking notice about the account a VAT input account names, derived on every read (MER-5393).", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "example": "VAT_INPUT_ACCOUNT_NOT_AN_ASSET", "enum": [ "VAT_INPUT_ACCOUNT_NOT_AN_ASSET" ] }, "message": { "type": "string", "example": "La cuenta 2.1.03. - Impuestos por Pagar es de tipo Pasivo, pero la cuenta de IVA crédito fiscal debe ser de tipo Activo: el IVA de las compras registrado aquí se lee como una deuda y no como crédito fiscal. Elige una cuenta de Activo (en la plantilla VE, 1.3.01. IVA crédito fiscal). Si la empresa no es contribuyente ordinario de IVA, sus compras no usan esta cuenta: su IVA va a la cuenta de IVA no deducible." } }, "type": "object" }, "VatInputAccount": { "required": [ "id", "account_id", "center_id", "status", "company_id", "account_code", "account_name", "center_code", "center_name", "warnings" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "0199e1a2-0000-7000-8000-0000000000b1" }, "account_id": { "type": "string", "format": "uuid", "example": "0199e1a2-0000-7000-8000-0000000000b2" }, "center_id": { "type": "string", "format": "uuid", "example": "0199e1a2-0000-7000-8000-0000000000b3" }, "status": { "type": "string", "example": "active", "enum": [ "active", "inactive" ] }, "company_id": { "type": "string", "format": "uuid", "example": "0199a3c1-0000-7000-8000-00000000c0de" }, "account_code": { "description": "Null when the account does not resolve in the company.", "type": "string", "example": "1.1.10.", "nullable": true }, "account_name": { "description": "Null when the account does not resolve in the company.", "type": "string", "example": "IVA crédito fiscal", "nullable": true }, "center_code": { "description": "Null when the center does not resolve in the company.", "type": "string", "example": "ADM", "nullable": true }, "center_name": { "description": "Null when the center does not resolve in the company.", "type": "string", "example": "Administración", "nullable": true }, "warnings": { "description": "VAT_INPUT_ACCOUNT_NOT_AN_ASSET when the account is not an asset (MER-5393); empty otherwise, and when the account does not resolve in the company.", "type": "array", "items": { "$ref": "#/components/schemas/VatInputAccountWarning" } } }, "type": "object" }, "VatInputAccountsPage": { "required": [ "items", "total", "per_page", "current_page", "meta" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/VatInputAccount" } }, "total": { "type": "integer", "example": 1, "minimum": 0 }, "per_page": { "type": "integer", "example": 20 }, "current_page": { "type": "integer", "example": 1 }, "meta": { "$ref": "#/components/schemas/AccountingSettingsStatusListMeta" } }, "type": "object" }, "PostingAccountsPage": { "required": [ "items", "total", "per_page", "current_page", "meta" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/PostingAccount" } }, "total": { "type": "integer", "example": 2, "minimum": 0 }, "per_page": { "type": "integer", "example": 20 }, "current_page": { "type": "integer", "example": 1 }, "meta": { "$ref": "#/components/schemas/AccountingSettingsStatusListMeta" } }, "type": "object" }, "PostingAccount": { "required": [ "id", "role", "account_id", "account_code", "account_name", "center_id", "center_code", "center_name", "status", "company_id" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "0199a3b2-6c1e-7f3a-9d2b-1a2b3c4d5e6f" }, "role": { "type": "string", "example": "realized_exchange_gain", "enum": [ "realized_exchange_gain", "realized_exchange_loss", "unrealized_exchange_gain", "unrealized_exchange_loss", "bank_fees", "cash_shortage", "cash_overage", "sales_returns", "purchase_returns", "customer_advances", "supplier_advances", "vat_withholding_payable", "islr_withholding_payable", "igtf_payable", "vat_withholding_supported", "islr_withholding_supported", "reported_withholding_pending", "igtf_expense", "non_deductible_vat" ] }, "account_id": { "type": "string", "format": "uuid" }, "account_code": { "type": "string", "example": "4.2.01.", "nullable": true }, "account_name": { "type": "string", "example": "Ganancia cambiaria realizada", "nullable": true }, "center_id": { "type": "string", "format": "uuid" }, "center_code": { "type": "string", "example": "GEN", "nullable": true }, "center_name": { "type": "string", "example": "General", "nullable": true }, "status": { "type": "string", "example": "active", "enum": [ "active", "inactive" ] }, "company_id": { "type": "string", "format": "uuid" } }, "type": "object" }, "AccountingReadinessWarnings": { "description": "Non-blocking notices; they never change `ready` (MER-2951). Always present, empty when there is nothing to warn about.", "type": "array", "items": { "properties": { "reason_code": { "type": "string" }, "subject_type": { "type": "string" }, "subject_id": { "type": "string" }, "human_message": { "type": "string" }, "details": { "type": "array", "items": { "type": "string" } } }, "type": "object" } }, "AttachmentStorageUnavailableProblem": { "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string", "example": "Service Unavailable" }, "status": { "type": "integer", "example": 503 }, "detail": { "type": "string", "example": "Los adjuntos no están disponibles en este momento. Contacta al administrador." }, "error_code": { "type": "string", "enum": [ "attachment_storage_unavailable" ] }, "errors": { "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" }, "CollaborationCommentWriteProblem": { "required": [ "title", "status", "detail", "error_code" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer", "enum": [ 422 ] }, "detail": { "type": "string" }, "error_code": { "type": "string", "nullable": true, "enum": [ null, "invalid_comment_body", "comment_mention_not_allowed", "comment_mention_limit_exceeded" ] }, "errors": { "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "rejected_user_ids": { "type": "array", "items": { "type": "integer" } } }, "type": "object" }, "LabelAssignmentProblem": { "description": "The Problem a label assignment answers: a `can:` 403, a missing document or label, or an archived label.", "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "detail": { "type": "string" }, "error_code": { "type": "string", "example": "collaboration_document_not_found", "nullable": true }, "errors": { "type": "object", "nullable": true } }, "type": "object" }, "LabelAssignmentMiddlewareMessage": { "description": "The message Laravel answers before the controller: unauthenticated, an unknown tenant or a malformed id.", "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" }, "InboxProblem": { "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "error_code": { "type": "string", "nullable": true }, "errors": { "type": "object", "nullable": true, "additionalProperties": true } }, "type": "object" }, "InboxEvent": { "required": [ "id", "type", "actor", "created_at", "read_at", "comment_excerpt", "comment_id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "assigned", "unassigned", "mentioned", "commented" ] }, "actor": { "required": [ "user_id", "name" ], "properties": { "user_id": { "type": "integer", "nullable": true }, "name": { "type": "string" } }, "type": "object" }, "created_at": { "type": "string", "format": "date-time" }, "read_at": { "type": "string", "format": "date-time", "nullable": true }, "comment_id": { "type": "string", "format": "uuid", "nullable": true }, "comment_excerpt": { "type": "string", "nullable": true } }, "type": "object" }, "InboxGroup": { "required": [ "document_type", "document_id", "event_count", "has_unread", "representative", "events", "document" ], "properties": { "document_type": { "type": "string" }, "document_id": { "type": "string", "format": "uuid" }, "event_count": { "type": "integer" }, "has_unread": { "type": "boolean" }, "representative": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InboxEvent" } ] }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/InboxEvent" } }, "document": { "required": [ "type", "id", "code", "title", "status", "responsible_user_id", "responsible_user_name", "navigation" ], "properties": { "type": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "code": { "type": "string", "nullable": true }, "title": { "type": "string" }, "status": { "type": "string" }, "responsible_user_id": { "type": "integer", "nullable": true }, "responsible_user_name": { "type": "string", "nullable": true }, "navigation": { "type": "object", "additionalProperties": { "type": "string" } } }, "type": "object" } }, "type": "object" }, "InboxPage": { "required": [ "items", "next_cursor", "per_page" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/InboxGroup" } }, "next_cursor": { "type": "string", "nullable": true }, "per_page": { "type": "integer" } }, "type": "object" }, "InboxCounts": { "description": "Unread visible document groups; hidden, deleted, inaccessible and snoozed events are excluded. Other companies are checked against current membership and permissions.", "required": [ "current", "others" ], "properties": { "current": { "type": "integer" }, "others": { "type": "array", "items": { "required": [ "company_id", "count" ], "properties": { "company_id": { "type": "string", "format": "uuid" }, "count": { "type": "integer" } }, "type": "object" } } }, "type": "object" }, "NotificationPreferencesValidationProblem": { "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer", "enum": [ 422 ] }, "detail": { "type": "string" }, "error_code": { "description": "Null for request validation errors", "type": "string", "nullable": true }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object", "additionalProperties": false }, "NotificationPreferences": { "required": [ "email_assignments", "email_mentions", "email_comments" ], "properties": { "email_assignments": { "type": "boolean" }, "email_mentions": { "type": "boolean" }, "email_comments": { "type": "boolean" } }, "type": "object", "additionalProperties": false }, "CompanyProblem": { "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "detail": { "type": "string", "example": "El id de la empresa ya está en uso." }, "error_code": { "type": "string", "example": "company_already_exists", "nullable": true }, "errors": { "description": "Field-keyed messages of a validation 422; null otherwise.", "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" }, "CompanyRecord": { "required": [ "id", "name", "country", "timezone", "number_format", "functional_currency", "reporting_currency", "status", "created_at", "capabilities" ], "properties": { "id": { "type": "string", "example": "123e4567-e89b-12d3-a456-426655440000" }, "name": { "type": "string", "example": "MedineTech" }, "country": { "type": "string", "example": "VE" }, "number_format": { "type": "string", "example": "es_VE", "enum": [ "es_VE", "en" ] }, "timezone": { "type": "string", "example": "America/Caracas" }, "functional_currency": { "type": "string", "example": "USD" }, "reporting_currency": { "type": "string", "example": "USD" }, "status": { "type": "string", "example": "ACTIVE", "enum": [ "ACTIVE", "INACTIVE" ] }, "created_at": { "description": "ISO 8601 UTC instant the company was created; null only for a legacy row that never recorded it.", "type": "string", "format": "date-time", "example": "2026-05-03T14:03:11+00:00", "nullable": true }, "capabilities": { "required": [ "fiscal_profile", "bank_directory" ], "properties": { "fiscal_profile": { "description": "Whether the company's country enables the Company Fiscal Profile.", "type": "boolean", "example": true }, "bank_directory": { "description": "Bank-name suggestion directory for the company's country; null when none.", "type": "string", "example": "VE", "nullable": true, "enum": [ "VE" ] } }, "type": "object" }, "fiscal_profile": { "description": "Null while no profile is defined.", "required": [ "rif", "legal_name", "fiscal_address", "issuance_channel", "active_control_series" ], "properties": { "rif": { "description": "Canonical RIF, L-NNNNNNNN-D.", "type": "string", "example": "J-12345678-4" }, "legal_name": { "type": "string", "example": "Inversiones Ejemplo, C.A." }, "fiscal_address": { "type": "string", "example": "Av. Francisco de Miranda, Torre Parque Cristal, Caracas" }, "issuance_channel": { "type": "string", "example": "fiscal_machine", "enum": [ "fiscal_machine", "free_form", "digital_printer", "seniat_portal" ] }, "active_control_series": { "description": "The Active Control Series the proposed control number starts from; null when the company has none.", "type": "string", "example": "00", "nullable": true } }, "type": "object", "nullable": true } }, "type": "object" }, "CompanyListRow": { "required": [ "id", "name", "country", "functional_currency", "status" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "0199b1aa-0000-7000-8000-00000000a002" }, "name": { "type": "string", "example": "MedineTech" }, "country": { "type": "string", "example": "VE" }, "functional_currency": { "type": "string", "example": "USD" }, "status": { "type": "string", "example": "ACTIVE", "enum": [ "ACTIVE", "INACTIVE" ] } }, "type": "object" }, "CompaniesListMeta": { "required": [ "total", "per_page", "current_page", "counts" ], "properties": { "total": { "type": "integer", "example": 2 }, "per_page": { "type": "integer", "example": 50 }, "current_page": { "type": "integer", "example": 1 }, "counts": { "description": "The user's companies per status under every filter but status, zero-filled.", "required": [ "ACTIVE", "INACTIVE" ], "properties": { "ACTIVE": { "type": "integer", "example": 1 }, "INACTIVE": { "type": "integer", "example": 1 } }, "type": "object" } }, "type": "object" }, "CompaniesPage": { "required": [ "items", "total", "per_page", "current_page", "meta" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyListRow" } }, "total": { "type": "integer", "example": 2 }, "per_page": { "type": "integer", "example": 50 }, "current_page": { "type": "integer", "example": 1 }, "meta": { "$ref": "#/components/schemas/CompaniesListMeta" } }, "type": "object" }, "CompanyUserDefaults": { "required": [ "accounting_center_id", "location_id" ], "properties": { "accounting_center_id": { "type": "string", "format": "uuid", "nullable": true }, "location_id": { "type": "string", "format": "uuid", "nullable": true } }, "type": "object", "additionalProperties": false }, "BasicSetupState": { "required": [ "company_id", "completed", "provisioning_status" ], "properties": { "company_id": { "type": "string", "format": "uuid" }, "completed": { "description": "True when canonical answers have been accepted.", "type": "boolean" }, "provisioning_status": { "type": "string", "enum": [ "not_started", "preparing", "ready" ] } }, "type": "object" }, "BasicSetupProblem": { "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "error_code": { "type": "string", "nullable": true }, "errors": { "type": "object", "nullable": true } }, "type": "object" }, "BasicSetupMessage": { "required": [ "message" ], "properties": { "message": { "type": "string" } }, "type": "object" }, "BasicSetupUnverifiedEmail": { "required": [ "message", "status", "detail" ], "properties": { "message": { "type": "string" }, "status": { "type": "string", "enum": [ "email_not_verified" ] }, "detail": { "type": "string" } }, "type": "object" }, "BasicSetupAccessDenied": { "required": [ "title", "status", "detail" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer", "example": 403 }, "detail": { "type": "string" }, "reason": { "type": "string" } }, "type": "object" }, "FiscalPeriod": { "description": "One Fiscal Period of the company (ADR 0264, ADR 0265): a fortnight when the company is a special taxpayer on the month's first day, a calendar month otherwise. `version` is the current Declared Set version, null until the period first freezes. Who froze it and when show only while it is in review or closed, who closed it only while it is closed; who reopened it, when and why show as last recorded.", "required": [ "period", "period_type", "starts_on", "ends_on", "status", "version", "frozen_at", "frozen_by", "closed_at", "closed_by", "reopened_at", "reopened_by", "reopen_reason" ], "properties": { "period": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])(-[12])?$", "example": "2026-09" }, "period_type": { "type": "string", "example": "month", "enum": [ "month", "fortnight" ] }, "starts_on": { "type": "string", "format": "date", "example": "2026-09-01" }, "ends_on": { "type": "string", "format": "date", "example": "2026-09-30" }, "status": { "type": "string", "example": "in_review", "enum": [ "open", "in_review", "closed" ] }, "version": { "type": "integer", "example": 1, "nullable": true, "minimum": 1 }, "frozen_at": { "type": "string", "format": "date-time", "example": "2026-10-05T16:00:00+00:00", "nullable": true }, "frozen_by": { "description": "The user who froze the current version; null while the period is open.", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "example": "42" }, "name": { "description": "Null when the user no longer exists.", "type": "string", "example": "Ana Contadora", "nullable": true } }, "type": "object", "nullable": true }, "closed_at": { "type": "string", "format": "date-time", "example": null, "nullable": true }, "closed_by": { "description": "The user who closed the period; null unless it is closed.", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "example": "11" }, "name": { "description": "Null when the user no longer exists.", "type": "string", "example": "Luis Auditor", "nullable": true } }, "type": "object", "nullable": true }, "reopened_at": { "type": "string", "format": "date-time", "example": null, "nullable": true }, "reopened_by": { "description": "The user who last reopened the period; null when it was never reopened.", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "example": "11" }, "name": { "description": "Null when the user no longer exists.", "type": "string", "example": "Luis Auditor", "nullable": true } }, "type": "object", "nullable": true }, "reopen_reason": { "type": "string", "example": null, "nullable": true } }, "type": "object" }, "FiscalPeriodListItem": { "description": "A Fiscal Period as the list shows it, with whether it may freeze now and whether it may reopen.", "allOf": [ { "$ref": "#/components/schemas/FiscalPeriod" }, { "required": [ "freezable", "reopenable" ], "properties": { "freezable": { "description": "True when freezing it now passes every order rule: it has ended in the company's timezone, it is open, no other period is in review and it is the period right after the latest closed one, or, while none is closed, the declarations start (any ended period before the first freeze). Its readiness is not checked.", "type": "boolean", "example": true }, "reopenable": { "description": "True when it is the latest closed period and no other period is in review; the reopen permission is checked separately.", "type": "boolean", "example": false } }, "type": "object" } ] }, "FiscalPeriodVersion": { "description": "One version of a Fiscal Period's Declared Set: who froze it and when, and, once an unfreeze or a reopen superseded it, who did it, when and why. Its documents stay readable through `declared-documents?version=N`.", "required": [ "version", "frozen_at", "frozen_by", "superseded_at", "superseded_by", "superseded_reason" ], "properties": { "version": { "type": "integer", "example": 1, "minimum": 1 }, "frozen_at": { "type": "string", "format": "date-time", "example": "2026-10-05T14:00:00+00:00" }, "frozen_by": { "description": "The user who froze this version.", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "example": "42" }, "name": { "description": "Null when the user no longer exists.", "type": "string", "example": "Ana Contadora", "nullable": true } }, "type": "object" }, "superseded_at": { "description": "When an unfreeze or a reopen superseded this version; null while it is current.", "type": "string", "format": "date-time", "example": "2026-10-06T15:00:00+00:00", "nullable": true }, "superseded_by": { "description": "The user who superseded this version; null while it is current.", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "example": "42" }, "name": { "description": "Null when the user no longer exists.", "type": "string", "example": "Ana Contadora", "nullable": true } }, "type": "object", "nullable": true }, "superseded_reason": { "description": "Why the unfreeze or the reopen superseded it; null while it is current.", "type": "string", "example": "Corrección de número de control de FV03", "nullable": true } }, "type": "object" }, "FiscalPeriodDetail": { "description": "A Fiscal Period with every version of its Declared Set, oldest first; a period that never froze has none.", "allOf": [ { "$ref": "#/components/schemas/FiscalPeriod" }, { "required": [ "versions" ], "properties": { "versions": { "description": "Oldest first.", "type": "array", "items": { "$ref": "#/components/schemas/FiscalPeriodVersion" } } }, "type": "object" } ] }, "FiscalPeriodGap": { "description": "An essential gap that keeps a period from freezing, naming the document to fix.", "required": [ "code", "book", "document_type", "document_id", "document_code", "affected_document_id", "book_date" ], "properties": { "code": { "description": "WITHHOLDING_NOT_CERTIFIED: a VAT withholding practiced on a purchase has no issued certificate.", "type": "string", "example": "DOCUMENT_NUMBER_MISSING", "enum": [ "DOCUMENT_NOT_VALUED_IN_BOLIVARES", "DOCUMENT_NUMBER_MISSING", "WITHHOLDING_NOT_CERTIFIED" ] }, "book": { "type": "string", "example": "sales", "enum": [ "sales", "purchases" ] }, "document_type": { "type": "string", "example": "invoice", "enum": [ "invoice", "credit_note", "debit_note", "received_vat_withholding", "practiced_vat_withholding" ] }, "document_id": { "type": "string", "format": "uuid" }, "document_code": { "description": "The ERP code of the document; for a practiced VAT withholding, its purchase's code.", "type": "string", "example": "INV00012" }, "affected_document_id": { "description": "The document to act on: a note's origin, a practiced withholding's purchase or a received withholding line's invoice; null for an invoice.", "type": "string", "format": "uuid", "example": null, "nullable": true }, "book_date": { "type": "string", "format": "date", "example": "2026-10-03" } }, "type": "object" }, "FiscalPeriodWarning": { "description": "Something worth reviewing before freezing, which never keeps the period from freezing.", "required": [ "code", "book", "count" ], "properties": { "code": { "description": "Drafts dated in the period's own days: they are not declared, and if approved after it freezes they are declared later as late documents. UNIDENTIFIED_BUYER_AFTER_LEGAL_DATE (book sales, count only, MER-5756, ADR 0352): declared invoices to the company's Consumidor final dated in the declaration window from 2027-04-19 whose buyer lacks a name or a RIF, cédula or passport (PA SNAT/2026/00093 art. 8.6).", "type": "string", "example": "DRAFTS_DATED_IN_PERIOD", "enum": [ "DRAFTS_DATED_IN_PERIOD", "SALES_DISPATCHES_WITHOUT_INVOICE", "UNREPORTED_CONTINGENCIES", "FREE_FORM_AFTER_LEGAL_DATE", "UNIDENTIFIED_BUYER_AFTER_LEGAL_DATE" ] }, "book": { "type": "string", "example": "sales", "enum": [ "sales", "purchases" ] }, "count": { "type": "integer", "example": 1, "minimum": 1 }, "dispatches": { "type": "array", "items": { "required": [ "id", "code" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" } }, "type": "object" } } }, "type": "object" }, "DeclaredDocument": { "description": "One row of a Declared Set: what the VAT books print of a document, signed in bolívares. A credit note subtracts, a cancelled document that carries its number is declared with zero amounts, and a document dated before its period is late. `total_ves` equals the sum of the eleven amount columns.", "required": [ "book", "document_type", "document_id", "late", "book_date", "document_date", "registration_date", "counterparty_document_type", "counterparty_document_number", "counterparty_legal_name", "counterparty_vat_taxpayer_type", "document_number", "control_number", "affected_document_number", "affected_control_number", "affected_document_id", "status", "currency", "rate", "total_ves", "exempt_ves", "exonerated_ves", "not_subject_ves", "export_ves", "other_ves", "vat_general_base_ves", "vat_general_tax_ves", "vat_reduced_base_ves", "vat_reduced_tax_ves", "vat_additional_base_ves", "vat_additional_tax_ves", "withheld_vat_ves", "withholding_certificate_number" ], "properties": { "book": { "type": "string", "example": "sales", "enum": [ "sales", "purchases" ] }, "document_type": { "type": "string", "example": "credit_note", "enum": [ "invoice", "credit_note", "debit_note", "received_vat_withholding", "practiced_vat_withholding" ] }, "document_id": { "type": "string", "format": "uuid" }, "late": { "description": "True when the Book Date falls before the period's start: approved, registered or received after the earlier period froze.", "type": "boolean", "example": false }, "book_date": { "type": "string", "format": "date", "example": "2026-09-16" }, "document_date": { "type": "string", "format": "date", "example": "2026-09-16" }, "registration_date": { "type": "string", "format": "date", "example": null, "nullable": true }, "counterparty_document_type": { "type": "string", "example": "rif", "nullable": true }, "counterparty_document_number": { "type": "string", "example": "J-00123072-6", "nullable": true }, "counterparty_legal_name": { "type": "string", "example": "Cliente A C.A.", "nullable": true }, "counterparty_vat_taxpayer_type": { "type": "string", "example": "ordinary", "nullable": true }, "document_number": { "type": "string", "example": "00000002", "nullable": true }, "control_number": { "type": "string", "example": "00-00000002", "nullable": true }, "affected_document_number": { "description": "The number of the document a note affects.", "type": "string", "example": "00000001", "nullable": true }, "affected_control_number": { "type": "string", "example": "00-00000001", "nullable": true }, "affected_document_id": { "description": "The ERP id of the document whose numbers fill the affected columns: a note's origin; a practiced withholding's purchase; a received withholding line's invoice; null for an invoice.", "type": "string", "format": "uuid", "nullable": true }, "status": { "type": "string", "example": "active", "enum": [ "active", "cancelled" ] }, "currency": { "type": "string", "example": "USD" }, "rate": { "description": "Bolívares per unit of the document currency: 1 for a bolívar document, the functional rate when the functional book keeps bolívares, else null.", "type": "string", "pattern": "^\\d+\\.\\d{8}$", "example": "100.00000000", "nullable": true }, "input_vat_deductible": { "description": "Eligibility frozen with this declared row; historical rows retain their original treatment.", "type": "boolean" }, "total_ves": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "-1160.00" }, "exempt_ves": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "0.00" }, "exonerated_ves": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "0.00" }, "not_subject_ves": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "0.00" }, "export_ves": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "0.00" }, "other_ves": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "0.00" }, "vat_general_base_ves": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "-1000.00" }, "vat_general_tax_ves": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "-160.00" }, "vat_reduced_base_ves": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "0.00" }, "vat_reduced_tax_ves": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "0.00" }, "vat_additional_base_ves": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "0.00" }, "vat_additional_tax_ves": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "0.00" }, "withheld_vat_ves": { "description": "The VAT a withholding withheld, in bolívares; negative for a received withholding adjustment (ADR 0263); null for an invoice or a note.", "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": null, "nullable": true }, "withholding_certificate_number": { "type": "string", "example": null, "nullable": true } }, "type": "object" }, "DeclaredDocumentsMeta": { "description": "Which Declared Set the page reads and how it pages.", "required": [ "period", "version", "superseded_at", "total", "per_page", "current_page", "last_page" ], "properties": { "period": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])(-[12])?$", "example": "2026-09" }, "version": { "type": "integer", "example": 1, "minimum": 1 }, "superseded_at": { "description": "When an unfreeze or a reopen superseded this version; null while it is current.", "type": "string", "format": "date-time", "example": null, "nullable": true }, "total": { "type": "integer", "example": 5, "minimum": 0 }, "per_page": { "type": "integer", "example": 50, "maximum": 100, "minimum": 1 }, "current_page": { "type": "integer", "example": 1, "minimum": 1 }, "last_page": { "description": "At least 1, even when the set is empty.", "type": "integer", "example": 1, "minimum": 1 } }, "type": "object", "additionalProperties": false }, "FiscalPeriodProblem": { "description": "A refusal of the fiscal-periods endpoints. Besides the standard members, a refusal carries what a client renders it from: `missing` for fiscal_period_not_ready, `expected_period` for fiscal_period_out_of_order, `expected_period_type` for fiscal_period_type_mismatch, `period_in_review` for fiscal_period_review_in_progress and `period_status` for fiscal_period_status_conflict. A reopen refusal reuses them: fiscal_period_out_of_order names the latest closed period in `expected_period`, and fiscal_period_review_in_progress names the later period in review.", "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string" }, "error_code": { "type": "string", "example": "fiscal_period_not_ready" }, "errors": { "type": "object", "example": null, "nullable": true }, "missing": { "type": "array", "items": { "$ref": "#/components/schemas/FiscalPeriodGap" } }, "expected_period": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])(-[12])?$", "example": "2026-10" }, "expected_period_type": { "type": "string", "example": "fortnight", "enum": [ "month", "fortnight" ] }, "period_in_review": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])(-[12])?$", "example": "2026-09" }, "period_status": { "type": "string", "example": "in_review", "enum": [ "open", "in_review", "closed" ] } }, "type": "object" }, "FrozenFiscalPeriod": { "description": "The Fiscal Period whose current Declared Set holds a document (MER-3837): its key and whether it is in review or closed. An open period freezes nothing.", "required": [ "period", "status" ], "properties": { "period": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])(-[12])?$", "example": "2026-09" }, "status": { "type": "string", "example": "closed", "enum": [ "in_review", "closed" ] } }, "type": "object" }, "DocumentInFrozenFiscalPeriodProblem": { "description": "A write refused because the current Declared Set of a Fiscal Period in review or closed holds the document (document_in_frozen_fiscal_period, ADR 0264, MER-3837): cancelling it, correcting its fiscal identity or voiding its withholding would change what the period declared. It is corrected with a note, or once the period returns to open. Nothing is written.", "required": [ "title", "status", "detail", "error_code", "errors", "fiscal_period" ], "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "detail": { "description": "Spanish copy for a person. Names the period as the screens do («Septiembre 2026», «1–15 sep 2026», «16–30 sep 2026»; MER-4866). Branch on error_code and read the period key from fiscal_period.period, never from detail.", "type": "string", "example": "Declarado en el período fiscal Septiembre 2026 (cerrado). Emite una nota o vuelve el período a abierto." }, "error_code": { "type": "string", "example": "document_in_frozen_fiscal_period", "enum": [ "document_in_frozen_fiscal_period" ] }, "errors": { "type": "object", "example": null, "nullable": true }, "fiscal_period": { "$ref": "#/components/schemas/FrozenFiscalPeriod" } }, "type": "object" }, "FiscalPeriodValidationProblem": { "description": "A request the validator refused, naming each field in `errors`.", "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string", "example": "The given data was invalid." }, "error_code": { "type": "string", "example": null, "nullable": true }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" }, "FiscalIgtfCollectionOutcome": { "required": [ "outcome", "reason", "numeral", "rule_id", "percentage" ], "properties": { "outcome": { "description": "not_evaluated: the company has no Fiscal Profile; not_perceived: the line bears no perceived IGTF (see reason); perceived: the line carries the numeral 6 rate; unclassified: a covered line that cannot be classified, which blocks the collection at its readiness check (see reason).", "type": "string", "example": "perceived", "enum": [ "not_evaluated", "not_perceived", "perceived", "unclassified" ] }, "reason": { "description": "Why the line is not_perceived (legal_tender_currency, financial_system_intermediated, company_not_perception_agent) or unclassified (company_tax_attributes_not_configured, rule_not_in_force); null otherwise.", "type": "string", "example": null, "nullable": true, "enum": [ "legal_tender_currency", "financial_system_intermediated", "company_not_perception_agent", "company_tax_attributes_not_configured", "rule_not_in_force" ] }, "numeral": { "description": "The IGTF law art. 4 numeral of the perceived rate; null unless perceived.", "type": "integer", "example": 6, "nullable": true, "maximum": 6, "minimum": 1 }, "rule_id": { "description": "The IGTF rate the line freezes; null unless perceived.", "type": "string", "format": "uuid", "example": "c650952d-9c41-5647-a30b-9ed15a96f783", "nullable": true }, "percentage": { "description": "The perceived rate as an exact scale-2 decimal string; null unless perceived.", "type": "string", "pattern": "^\\d{1,3}\\.\\d{2}$", "example": "3.00", "nullable": true } }, "type": "object", "additionalProperties": false }, "FiscalIgtfApplicabilityPreview": { "required": [ "instrument_id", "date", "collection", "paid_suggestion" ], "properties": { "instrument_id": { "description": "The previewed payment instrument, lowercased.", "type": "string", "format": "uuid", "example": "0199e0a0-0000-7000-8000-0000000000b1" }, "date": { "description": "The day of the cash event, as asked.", "type": "string", "format": "date", "example": "2026-09-11" }, "collection": { "$ref": "#/components/schemas/FiscalIgtfCollectionOutcome" }, "paid_suggestion": { "description": "The numeral 6 IGTF a provider may charge on a payment line: present when the instrument is in a foreign currency or crypto-asset, operates outside the national banking system, numeral 6 is in force on `date`, and the provider named by `provider_id` is a special taxpayer on `date`, a reading an accountant should confirm, whatever the company's own fiscal standing; null otherwise, and always null without `provider_id`. A suggestion only, it never blocks.", "required": [ "rule_id", "percentage" ], "properties": { "rule_id": { "type": "string", "format": "uuid", "example": "c650952d-9c41-5647-a30b-9ed15a96f783" }, "percentage": { "type": "string", "pattern": "^\\d{1,3}\\.\\d{2}$", "example": "3.00" } }, "type": "object", "nullable": true, "additionalProperties": false } }, "type": "object", "additionalProperties": false }, "FiscalIslrConcept": { "required": [ "rule_id", "code", "label", "percentage", "base_percentage", "min_base_ut", "subtractor_factor", "subtractor_bs", "effective_from", "source_article", "matrix_rule_id", "matrix_version" ], "properties": { "rule_id": { "description": "The rule id an ISLR withholding line snapshots. Stable across environments: derived from country, code, person type and effective_from.", "type": "string", "format": "uuid", "example": "22adf5c6-5d67-5ab3-a4fd-ac3eec1de131" }, "code": { "description": "Stable Decree 1.808 art. 9 concept code; the numeral lives in source_article.", "type": "string", "pattern": "^[a-z][a-z0-9_]{0,63}$", "example": "professional_fees" }, "label": { "description": "Spanish label for the concept selector.", "type": "string", "example": "Honorarios profesionales no mercantiles", "maxLength": 120 }, "percentage": { "description": "Withholding rate, as an exact scale-2 decimal string.", "type": "string", "pattern": "^\\d{1,3}\\.\\d{2}$", "example": "3.00" }, "base_percentage": { "description": "Share of the payment the rate applies to, as an exact scale-2 decimal string.", "type": "string", "pattern": "^\\d{1,3}\\.\\d{2}$", "example": "100.00" }, "min_base_ut": { "description": "Minimum base in tax units, scale 4; 0.0000 means every payment.", "type": "string", "pattern": "^\\d{1,6}\\.\\d{4}$", "example": "83.3334" }, "subtractor_factor": { "description": "Decree 1.808 art. 9 Par. 2 subtractor factor in tax units, scale 4; null when the payee type takes no subtractor (anyone but a resident natural person).", "type": "string", "pattern": "^\\d{1,6}\\.\\d{4}$", "example": "83.3334", "nullable": true }, "subtractor_bs": { "description": "Subtractor in bolívares at the tax unit in force (UT × rate × factor). Display value rounded half-up once; withholding subtracts the unrounded UT × rate × factor. Null without a subtractor factor or without a tax unit in force on `date`.", "type": "string", "pattern": "^\\d+\\.\\d{2}$", "example": "107.50", "nullable": true }, "effective_from": { "description": "First day the concept applies to payments.", "type": "string", "format": "date", "example": "1997-05-12" }, "source_article": { "type": "string", "example": "Decreto 1.808 art. 9 n. 1 lit. b", "maxLength": 120 }, "matrix_rule_id": { "description": "Fiscal rules matrix row that researched the concept.", "type": "string", "pattern": "^[A-Z]+-\\d{2}$", "example": "ISLR-01" }, "matrix_version": { "description": "Newest fiscal rules matrix version that changed the row the concept was researched from.", "type": "string", "example": "2026-10-09-research-4" } }, "type": "object", "additionalProperties": false }, "FiscalIslrWithholding": { "description": "An ISLR withholding the company practised on a purchases invoice (MER-3700, MER-3702): its amounts, one row per ISLR Concept it withheld under with the catalog rule it snapshots, the certificate that certifies or certified it (MER-3701), the invoice and provider it was practised on, its voiding, the earlier trigger date a prior payment suggests and the remittance that paid it to SENIAT (MER-3703).", "required": [ "id", "purchases_invoice_id", "invoice_code", "invoice_number", "document_kind", "provider_id", "provider_name", "provider_islr_person_type", "status", "voidable", "remittable", "remittance", "trigger_date", "month", "trigger_date_superseded", "suggested_trigger_date", "suggested_month", "withheld_amount_ves", "relief_document", "concepts", "certificate", "voiding" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "0199e1b0-0000-7000-8000-000000000003" }, "purchases_invoice_id": { "type": "string", "format": "uuid", "example": "0199e1b0-0000-7000-8000-0000000000a3" }, "invoice_code": { "description": "The code of the purchases invoice or Supplier Debit Note withheld from, whose id opens its record as `document_kind` says; null if Purchases does not name it.", "type": "string", "example": "PIN26000003", "nullable": true }, "invoice_number": { "description": "The number the provider printed on the invoice.", "type": "string", "example": "FAC-FC03", "nullable": true }, "document_kind": { "description": "Which purchase was withheld from, so the row opens the right record (MER-5386): `invoice` (an invoice or an opening document) or `debit_note` (a Supplier Debit Note, whose code is `NDP…`); null if Purchases does not name it.", "type": "string", "example": "invoice", "nullable": true, "enum": [ "invoice", "debit_note" ] }, "provider_id": { "type": "string", "format": "uuid", "example": "0199e1b0-0000-7000-8000-0000000000b1" }, "provider_name": { "description": "The provider's legal name frozen on the invoice, else its current legal name or name.", "type": "string", "example": "Consultora PC", "nullable": true }, "provider_islr_person_type": { "description": "The provider's ISLR Person Type frozen when the withholding was determined.", "type": "string", "example": "natural_resident", "enum": [ "natural_resident", "natural_non_resident", "legal_domiciled", "legal_non_domiciled" ] }, "status": { "description": "`certified` once its certificate is issued; one of zero withholds nothing and stays `determined`; `remitted` once its month's remittance paid it to SENIAT (MER-3703), and `certified` again if that remittance is voided; `voided` once voided, by its own request or by cancelling its invoice, which a remitted one never is. Treat a status you do not know as not current.", "type": "string", "enum": [ "determined", "certified", "remitted", "voided" ] }, "voidable": { "description": "Whether it may be voided now, the rule the server applies: false once remitted or voided; offer «Anular» only when true and the user may review withholdings.", "type": "boolean" }, "remittable": { "description": "Whether a remittance may pay it now, the rule the server applies (MER-3703): true only while `certified`; select it for «Registrar enteramiento» of its `month` only when true.", "type": "boolean" }, "remittance": { "description": "The remittance not voided that paid it to SENIAT (MER-3703), whose id opens `GET fiscal/withholding-remittances/{id}` and is what «Anular enteramiento» voids; null while none stands.", "required": [ "id", "remitted_on", "bank_reference", "amount", "status" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "0199e1c0-0000-7000-8000-000000000031" }, "remitted_on": { "description": "The day it was paid to SENIAT.", "type": "string", "format": "date", "example": "2026-09-24" }, "bank_reference": { "type": "string", "example": "SIM-ISLR-09", "maxLength": 120 }, "amount": { "description": "The whole remittance's amount, not this row's.", "required": [ "amount", "currency" ], "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "example": "192.50" }, "currency": { "type": "string", "example": "VES" } }, "type": "object", "additionalProperties": false }, "status": { "description": "Only the remittance that stands is shown.", "type": "string", "enum": [ "recorded" ] } }, "type": "object", "nullable": true, "additionalProperties": false }, "trigger_date": { "description": "The invoice's registration date, the day it was determined. Never re-dated.", "type": "string", "format": "date", "example": "2026-09-24" }, "month": { "description": "The month of its trigger date, which is when it is declared and remitted. Never re-dated.", "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$", "example": "2026-09" }, "trigger_date_superseded": { "description": "A payment dated before the registration suggests an earlier trigger date (ADR 0189): flag it for the accounting review.", "type": "boolean" }, "suggested_trigger_date": { "description": "The earliest such payment's day; null unless flagged.", "type": "string", "format": "date", "example": "2026-08-28", "nullable": true }, "suggested_month": { "description": "The month of the suggested day; null unless flagged.", "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$", "example": "2026-08", "nullable": true }, "withheld_amount_ves": { "description": "The legal amount withheld, in bolívars: the sum of its concepts.", "type": "string", "pattern": "^\\d+\\.\\d{2}$", "example": "192.50" }, "relief_document": { "description": "What it relieved of the supplier's debt, in the invoice's Document Currency.", "required": [ "amount", "currency" ], "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "example": "192.50" }, "currency": { "type": "string", "example": "VES" } }, "type": "object", "additionalProperties": false }, "concepts": { "description": "One row per ISLR Concept it withheld under, in the order it was determined.", "type": "array", "items": { "required": [ "code", "label", "rule_id", "base_ves", "percentage", "subtractor_ves", "amount_ves", "reason" ], "properties": { "code": { "type": "string", "example": "professional_fees", "maxLength": 64 }, "label": { "description": "The Spanish label of the catalog rule.", "type": "string", "example": "Honorarios profesionales no mercantiles", "maxLength": 120 }, "rule_id": { "description": "The ISLR concept rule it snapshots (ADR 0192).", "type": "string", "format": "uuid", "example": "22adf5c6-5d67-5ab3-a4fd-ac3eec1de131" }, "base_ves": { "description": "The concept's base, in bolívars.", "type": "string", "pattern": "^\\d+\\.\\d{2}$", "example": "10000.00" }, "percentage": { "description": "The rate applied, a decimal string.", "type": "string", "pattern": "^\\d{1,3}\\.\\d{2}$", "example": "3.00" }, "subtractor_ves": { "description": "The concept's subtractor (sustraendo), in bolívars, rounded once exactly as its certificate prints it (MER-3705); also kept on a concept below the minimum, which subtracted nothing; null when the concept's rate has none.", "type": "string", "pattern": "^\\d+\\.\\d{2}$", "example": "107.50", "nullable": true }, "amount_ves": { "description": "What the concept withheld, in bolívars.", "type": "string", "pattern": "^\\d+\\.\\d{2}$", "example": "192.50" }, "reason": { "description": "Why it withheld nothing; null when it withheld.", "type": "string", "nullable": true, "enum": [ "below_minimum" ] } }, "type": "object", "additionalProperties": false }, "minItems": 1 }, "certificate": { "description": "The certificate that certifies it, or certified it once voided (it keeps its number), whose id opens `GET fiscal/withholding-certificates/{id}`; null while it has none, as for one of zero.", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/FiscalWithholdingCertificateSummary" } ] }, "voiding": { "description": "Why, when and by whom it was voided; null while it stands.", "required": [ "voided_at", "reason", "voided_by_user_id" ], "properties": { "voided_at": { "description": "ISO 8601 in UTC.", "type": "string", "format": "date-time", "example": "2026-10-12T14:30:00+00:00" }, "reason": { "type": "string", "example": "Factura cancelada", "maxLength": 500 }, "voided_by_user_id": { "type": "string", "example": "42", "nullable": true } }, "type": "object", "nullable": true, "additionalProperties": false } }, "type": "object", "additionalProperties": false }, "FiscalIslrWithholdingsMeta": { "description": "How the list of ISLR withholdings pages (MER-3702).", "required": [ "total", "per_page", "current_page", "last_page", "counts" ], "properties": { "total": { "description": "The withholdings every filter matches, `status` included.", "type": "integer", "example": 1, "minimum": 0 }, "per_page": { "type": "integer", "example": 50, "maximum": 100, "minimum": 1 }, "current_page": { "type": "integer", "example": 1, "minimum": 1 }, "last_page": { "description": "At least 1, even when nothing matches.", "type": "integer", "example": 1, "minimum": 1 }, "counts": { "description": "The withholdings of each status under every filter but `status`; the known statuses are always named, at zero when empty, and a status a later slice adds is listed too.", "required": [ "determined", "certified", "remitted", "voided" ], "properties": { "determined": { "type": "integer", "example": 0, "minimum": 0 }, "certified": { "type": "integer", "example": 1, "minimum": 0 }, "remitted": { "type": "integer", "example": 0, "minimum": 0 }, "voided": { "type": "integer", "example": 0, "minimum": 0 } }, "type": "object", "additionalProperties": { "type": "integer" } } }, "type": "object", "additionalProperties": false }, "FiscalIslrWithholdingVoidResult": { "description": "An ISLR withholding once voided (MER-3702): its status and why, when and by whom.", "required": [ "id", "status", "voiding" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "0199e1b0-0000-7000-8000-000000000003" }, "status": { "type": "string", "enum": [ "voided" ] }, "voiding": { "required": [ "voided_at", "reason", "voided_by_user_id" ], "properties": { "voided_at": { "description": "ISO 8601 in UTC.", "type": "string", "format": "date-time", "example": "2026-10-12T14:30:00+00:00" }, "reason": { "type": "string", "example": "Concepto mal clasificado; se reclasificará.", "maxLength": 500 }, "voided_by_user_id": { "description": "Who voided it; null outside a user's request.", "type": "string", "example": "42", "nullable": true } }, "type": "object", "additionalProperties": false } }, "type": "object", "additionalProperties": false }, "FiscalPerceivedIgtfLine": { "description": "One collection method line whose IGTF Perceived the company owes SENIAT (MER-3690): its collection and client, the day its IGTF was perceived, the IGTF in the line's currency and in bolívars, and the standing remittance that paid it, if any.", "required": [ "collection_method_line_id", "collection_id", "collection_code", "client_id", "client_name", "perceived_on", "fortnight", "igtf", "igtf_ves", "status", "remittable", "remittance" ], "properties": { "collection_method_line_id": { "description": "What `POST fiscal/withholding-remittances` names in `collection_method_line_ids`.", "type": "string", "format": "uuid", "example": "0199e0a0-0000-7000-8000-0000000014a1" }, "collection_id": { "description": "Opens `GET sales/collections/{id}`.", "type": "string", "format": "uuid", "example": "0199e0a0-0000-7000-8000-0000000014c0" }, "collection_code": { "type": "string", "example": "COB-000014" }, "client_id": { "type": "string", "format": "uuid", "example": "0199e0a0-0000-7000-8000-0000000000d0" }, "client_name": { "description": "The client's legal name, else its name; null when the client cannot be read.", "type": "string", "example": "Consumidor final D", "nullable": true }, "perceived_on": { "description": "The day the IGTF was perceived: the day the money was credited, else the collection's day.", "type": "string", "format": "date", "example": "2026-09-11" }, "fortnight": { "description": "The fortnight of `perceived_on`, the one it is remitted in.", "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])-[12]$", "example": "2026-09-1" }, "igtf": { "description": "The IGTF perceived, in the line's currency.", "required": [ "amount", "currency" ], "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "example": "1.80" }, "currency": { "type": "string", "example": "USDT" } }, "type": "object", "additionalProperties": false }, "igtf_ves": { "description": "The bolívars it credited to `igtf_payable` and a remittance pays; null when the company's functional book does not keep bolívars, which cannot be remitted.", "type": "string", "pattern": "^\\d+\\.\\d{2}$", "example": "208.80", "nullable": true }, "status": { "description": "`remitted` while a standing remittance pays it; treat a status you do not know as not remittable.", "type": "string", "enum": [ "pending_remittance", "remitted" ] }, "remittable": { "description": "The server's rule for selecting it into a remittance: `pending_remittance` and valued in bolívars.", "type": "boolean" }, "remittance": { "description": "The standing remittance that paid it, whose id opens `GET fiscal/withholding-remittances/{id}`; null while pending.", "required": [ "id", "remitted_on", "bank_reference", "amount", "status" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "0199e0a0-0000-7000-8000-000000000026" }, "remitted_on": { "type": "string", "format": "date", "example": "2026-09-24" }, "bank_reference": { "type": "string", "example": "SIM-Q1-IGTF-26" }, "amount": { "required": [ "amount", "currency" ], "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "example": "208.80" }, "currency": { "type": "string", "enum": [ "VES" ] } }, "type": "object", "additionalProperties": false }, "status": { "type": "string", "example": "recorded", "enum": [ "recorded", "voided" ] } }, "type": "object", "nullable": true, "additionalProperties": false } }, "type": "object", "additionalProperties": false }, "FiscalPerceivedIgtfMeta": { "description": "How the list of perceived IGTF pages and totals (MER-3690): the bolívars are those of the whole filtered result, never of one page.", "required": [ "total", "per_page", "current_page", "last_page", "counts", "igtf_ves", "igtf_ves_by_status" ], "properties": { "total": { "description": "The lines every filter matches, `status` included.", "type": "integer", "example": 1, "minimum": 0 }, "per_page": { "type": "integer", "example": 50, "maximum": 100, "minimum": 1 }, "current_page": { "type": "integer", "example": 1, "minimum": 1 }, "last_page": { "description": "At least 1, even when nothing matches.", "type": "integer", "example": 1, "minimum": 1 }, "counts": { "description": "The lines of each status under every filter but `status`, at zero when empty.", "required": [ "pending_remittance", "remitted" ], "properties": { "pending_remittance": { "type": "integer", "example": 0, "minimum": 0 }, "remitted": { "type": "integer", "example": 1, "minimum": 0 } }, "type": "object", "additionalProperties": false }, "igtf_ves": { "description": "The bolívars of the lines every filter matches, `status` included; lines not valued in bolívars add none.", "type": "string", "pattern": "^\\d+\\.\\d{2}$", "example": "208.80" }, "igtf_ves_by_status": { "description": "The bolívars of each status under every filter but `status`.", "required": [ "pending_remittance", "remitted" ], "properties": { "pending_remittance": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "example": "0.00" }, "remitted": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "example": "208.80" } }, "type": "object", "additionalProperties": false } }, "type": "object", "additionalProperties": false }, "PortalExportPreview": { "description": "A period's Portal Export as the format version in force on its first day would write it, never stored (MER-4155): the version and its validity, the period's days, how many of its withholdings it covers and their row errors. `downloadable` is the server's rule; the client never derives it.", "required": [ "format", "version", "valid_from", "valid_to", "spec_source", "acceptance", "period", "period_type", "period_starts_on", "period_ends_on", "row_count", "downloadable", "row_errors" ], "properties": { "format": { "type": "string", "example": "vat_withholding_txt", "enum": [ "vat_withholding_txt", "islr_withholding_xml" ] }, "version": { "description": "The label of the format version in force on the period's first day", "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,31}$" }, "valid_from": { "description": "The first day the version is in force", "type": "string", "format": "date", "example": "2026-01-01" }, "valid_to": { "description": "The last day the version is in force, inclusive; null while it is open-ended", "type": "string", "format": "date", "example": null, "nullable": true }, "spec_source": { "description": "The specification the version follows", "type": "string" }, "acceptance": { "$ref": "#/components/schemas/PortalExportAcceptance" }, "period": { "type": "string", "example": "2026-09-2" }, "period_type": { "type": "string", "example": "fortnight", "enum": [ "fortnight", "month" ] }, "period_starts_on": { "type": "string", "format": "date", "example": "2026-09-16" }, "period_ends_on": { "type": "string", "format": "date", "example": "2026-09-30" }, "row_count": { "description": "The period's withholdings the export covers: certified, remitted and positive determined ones, those with a row error included", "type": "integer", "example": 1, "minimum": 0 }, "downloadable": { "description": "True when the download would answer the file: today, when there is no row error", "type": "boolean", "example": true }, "row_errors": { "description": "By withholding trigger date then id, each withholding's spec-independent errors in rule order; the version's own errors after all of them", "type": "array", "items": { "$ref": "#/components/schemas/PortalExportRowError" } } }, "type": "object" }, "PortalExportAcceptance": { "description": "Whether a file the version wrote was accepted by the portal: `receipt_reference` is the portal's receipt, present only once accepted.", "required": [ "status", "receipt_reference" ], "properties": { "status": { "type": "string", "example": "unverified", "enum": [ "unverified", "accepted" ] }, "receipt_reference": { "type": "string", "example": null, "nullable": true } }, "type": "object" }, "PortalExportRowError": { "description": "A withholding the export cannot carry as it stands. `code` and `field` are open lists, so a client shows `message` for a code it does not know. Known codes: withholding_without_certificate, purchase_document_not_found, invalid_agent_rif, invalid_provider_rif, missing_invoice_number, missing_control_number. Known fields: certificate, purchases_invoice_id, agent_rif, provider_document_number, invoice_number, control_number.", "required": [ "withholding_id", "purchases_invoice_id", "certificate_id", "certificate_number", "field", "code", "message" ], "properties": { "withholding_id": { "type": "string", "format": "uuid" }, "purchases_invoice_id": { "type": "string", "format": "uuid" }, "certificate_id": { "description": "Null while the withholding has no issued certificate", "type": "string", "format": "uuid", "nullable": true }, "certificate_number": { "type": "string", "example": "20260900000001", "nullable": true }, "field": { "type": "string", "pattern": "^[a-z][a-z0-9_]*$", "example": "certificate" }, "code": { "type": "string", "pattern": "^[a-z][a-z0-9_]*$", "example": "withholding_without_certificate" }, "message": { "type": "string", "example": "La retención está determinada y no tiene un comprobante de retención emitido." } }, "type": "object" }, "PortalExportProblem": { "description": "A refusal of the Portal Export: portal_export_format_not_found (404) or invalid_portal_export_period (422, with errors.period).", "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string", "example": "<2026-09-3> no es una quincena; se esperaba YYYY-MM-1 o YYYY-MM-2, por ejemplo 2026-09-2" }, "error_code": { "type": "string", "example": "invalid_portal_export_period", "enum": [ "portal_export_format_not_found", "invalid_portal_export_period" ] }, "errors": { "type": "object", "example": { "period": [ "<2026-09-3> no es una quincena; se esperaba YYYY-MM-1 o YYYY-MM-2, por ejemplo 2026-09-2" ] }, "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" }, "PortalExportFormatUnavailableProblem": { "description": "No version of the format is in force on the period's first day, so nothing is read: what every period answers while the production registry ships no version (FORM-01).", "required": [ "title", "status", "detail", "error_code", "errors", "format", "period", "period_starts_on" ], "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string", "example": "No hay una versión vigente del formato para el período <2026-09-2>, que empieza el 2026-09-16" }, "error_code": { "type": "string", "example": "portal_export_format_unavailable", "enum": [ "portal_export_format_unavailable" ] }, "errors": { "type": "object", "example": null, "nullable": true }, "format": { "type": "string", "example": "vat_withholding_txt", "enum": [ "vat_withholding_txt", "islr_withholding_xml" ] }, "period": { "type": "string", "example": "2026-09-2" }, "period_starts_on": { "type": "string", "format": "date", "example": "2026-09-16" } }, "type": "object" }, "PortalExportInvalidProblem": { "description": "The export has row errors, so it is never written: `row_errors` is the list the preview shows for the same request.", "required": [ "title", "status", "detail", "error_code", "errors", "format", "period", "row_errors" ], "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string", "example": "El exporte para el portal del período <2026-09-2> tiene 1 error por corregir antes de descargarlo" }, "error_code": { "type": "string", "example": "portal_export_invalid", "enum": [ "portal_export_invalid" ] }, "errors": { "type": "object", "example": null, "nullable": true }, "format": { "type": "string", "example": "vat_withholding_txt", "enum": [ "vat_withholding_txt", "islr_withholding_xml" ] }, "period": { "type": "string", "example": "2026-09-2" }, "row_errors": { "type": "array", "items": { "$ref": "#/components/schemas/PortalExportRowError" }, "minItems": 1 } }, "type": "object" }, "PortalExportUnauthenticated": { "description": "The authentication middleware's refusal, returned before the controller runs.", "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" }, "PortalExportForbidden": { "description": "The route's can: middleware refusal (bootstrap/app.php normalizes it to the problem envelope).", "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string", "example": "Forbidden" }, "status": { "type": "integer", "example": 403 }, "detail": { "type": "string", "example": "You do not have permission to access this resource." }, "error_code": { "type": "string", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true } }, "type": "object" }, "PortalExportAccessRefused": { "description": "The company access or tenant membership middleware refusal; only tenant membership names a reason.", "required": [ "title", "status", "detail" ], "properties": { "title": { "type": "string", "example": "Forbidden" }, "status": { "type": "integer", "example": 403 }, "detail": { "type": "string", "example": "You do not have access to this company" }, "reason": { "description": "Present when tenant membership refuses the request", "type": "string" } }, "type": "object" }, "PurchaseBookLedgerCheck": { "description": "A month's Purchase Book checked against the ledger (MER-3845, PRD MER-2725) in two blocks of the same shape: `vat_input`, the input VAT, and `withholdings`, the VAT withheld. When `available` is false, `unavailable_reason` says why and both blocks carry null totals and empty lists; otherwise `unavailable_reason` is null and each block's totals are signed decimal strings in bolívares with `book_vat − ledger_vat = explained + unexplained`.", "required": [ "month", "currency", "available", "unavailable_reason", "vat_input", "withholdings" ], "properties": { "month": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$", "example": "2026-09" }, "currency": { "type": "string", "example": "VES", "enum": [ "VES" ] }, "available": { "description": "Whether the company's functional book can be checked against the book; never null.", "type": "boolean", "example": true }, "unavailable_reason": { "description": "Why the check is not available: the company's functional currency is not VES. Null when it is available.", "type": "string", "example": null, "nullable": true, "enum": [ "functional_currency_not_ves", null ] }, "vat_input": { "$ref": "#/components/schemas/PurchaseBookLedgerCheckBlock" }, "withholdings": { "$ref": "#/components/schemas/PurchaseBookLedgerCheckBlock" } }, "type": "object" }, "PurchaseBookLedgerCheckBlock": { "description": "One block of the Purchase Book's ledger check, with the Sales Book check's top-level fields. In `vat_input`, `book_vat` adds the general, reduced and additional VAT of every purchase invoice and supplier note of the month's declared sections, late rows included, and `ledger_vat` adds the debit − credit of the entries that link them. In `withholdings`, `book_vat` adds the VAT withheld of every practiced VAT withholding the month's declared sections declare, late ones included, and `ledger_vat` adds the credit − debit of the entries that link them. The totals are null and the lists empty when the check is not available.", "required": [ "book_vat", "ledger_vat", "explained", "unexplained", "differences", "other_movements" ], "properties": { "book_vat": { "description": "What the month's declared sections declare in the block, late rows included: the matching column of the book's summary.", "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "5280.00", "nullable": true }, "ledger_vat": { "description": "What the month's entries that link the block's documents posted on its accounts, in the functional book.", "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "5280.00", "nullable": true }, "explained": { "description": "The signed sum of the differences whose cause is not `unexplained`.", "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "0.00", "nullable": true }, "unexplained": { "description": "The signed sum of the `unexplained` differences; opposite ones may net to 0.00.", "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "0.00", "nullable": true }, "differences": { "description": "Every document whose two amounts differ: `unexplained` first, then `not_yet_declared`, `late` and `reversal_in_other_month`; then invoices, credit notes and debit notes (withholdings in their own block); then by number in natural order, a document without one last.", "type": "array", "items": { "$ref": "#/components/schemas/PurchaseBookLedgerDifference" } }, "other_movements": { "description": "Every other entry on the block's accounts in the month, one per entry, account and day, by date, entry code and account code: a VAT settlement in `vat_input`, a remittance in `withholdings`. Informative only: never in `ledger_vat` nor in the differences.", "type": "array", "items": { "$ref": "#/components/schemas/PurchaseBookLedgerOtherMovement" } } }, "type": "object" }, "PurchaseBookLedgerDifference": { "description": "A purchase invoice (FAC), supplier credit note (NC) or supplier debit note (ND) in `vat_input`, or a practiced VAT withholding (RET) in `withholdings`, whose declared amount differs from what the ledger posted for it in the month. `difference = book_vat − ledger_vat`, so a negative one means the ledger posted more; a credit note is negative on both sides. A FAC, NC or ND links as the book's rows do, by `document_type` and `document_id`; a RET's `document_id` is the VAT withholding's id, and a RET's `withholding_certificate_id` is its certificate's.", "required": [ "document_type", "document_id", "document_number", "book_vat", "ledger_vat", "difference", "cause", "withholding_certificate_id" ], "properties": { "document_type": { "type": "string", "example": "FAC", "enum": [ "FAC", "NC", "ND", "RET" ] }, "document_id": { "type": "string", "format": "uuid" }, "document_number": { "description": "The number it was declared with, in the month or in the month that declares it now (a RET's certificate number); null when no current Declared Set declares it.", "type": "string", "example": "FAC-FC01", "nullable": true }, "book_vat": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "0.00" }, "ledger_vat": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "1600.00" }, "difference": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "-1600.00" }, "cause": { "description": "Only `unexplained` is not explained by how the books work; more causes may be added.", "type": "string", "example": "not_yet_declared", "enum": [ "late", "not_yet_declared", "reversal_in_other_month", "unexplained" ] }, "withholding_certificate_id": { "description": "A RET's only: the ERP id of the company's VAT Withholding Certificate numbered as its `document_number`, whatever its status, for navigation only; its detail requires backoffice.fiscal.withholdings.view. Null for a FAC, NC or ND, for a RET without `document_number` and for a number no certificate carries.", "type": "string", "format": "uuid", "nullable": true } }, "type": "object" }, "PurchaseBookLedgerOtherMovement": { "description": "What one entry that links no document of the block moved on one of its accounts on one day, on the block's side: debit − credit in `vat_input`, so a VAT settlement crediting input VAT is negative; credit − debit in `withholdings`, so a remittance is negative. Its fields are the general ledger detail's, so it links as a ledger row does.", "required": [ "date", "transaction_id", "transaction_code", "transaction_type", "linkable_type", "linkable_id", "account_id", "account_code", "account_name", "amount" ], "properties": { "date": { "type": "string", "format": "date", "example": "2026-09-24" }, "transaction_id": { "type": "string", "format": "uuid" }, "transaction_code": { "type": "string", "example": "AS-000024" }, "transaction_type": { "type": "string", "example": "manual_entry.approved" }, "linkable_type": { "type": "string", "example": "manual_entry" }, "linkable_id": { "type": "string", "format": "uuid" }, "account_id": { "type": "string", "format": "uuid" }, "account_code": { "type": "string", "example": "1.3.01." }, "account_name": { "type": "string", "example": "IVA crédito fiscal" }, "amount": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "-3680.00" } }, "type": "object" }, "PurchaseBook": { "description": "A month's Purchase Book (MER-3844, ADR 0264, ADR 0265): the Company's header, one section per Fiscal Period of the month, oldest first, each adding up its rows in `subtotals`, and the `summary` adding up every section's subtotals, so an open section adds nothing. Every amount is in the bolívares `currency` names once.", "required": [ "month", "currency", "company", "sections", "summary" ], "properties": { "month": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$", "example": "2026-09" }, "currency": { "type": "string", "example": "VES", "enum": [ "VES" ] }, "company": { "$ref": "#/components/schemas/PurchaseBookCompany" }, "sections": { "description": "Oldest first: the month alone, or its first fortnight then its second for a special taxpayer.", "type": "array", "items": { "$ref": "#/components/schemas/PurchaseBookSection" } }, "summary": { "$ref": "#/components/schemas/PurchaseBookAmounts" } }, "type": "object" }, "PurchaseBookCompany": { "description": "The Company's current fiscal profile; both are null when it has none, and the book still renders.", "required": [ "legal_name", "rif" ], "properties": { "legal_name": { "type": "string", "example": "QA Fiscal Company, C.A.", "nullable": true }, "rif": { "type": "string", "example": "J-00000000-0", "nullable": true } }, "type": "object" }, "PurchaseBookSection": { "description": "One Fiscal Period's part of the book. `version` is the Declared Set version its rows come from, null while the period is open: never frozen, unfrozen or reopened. Unlike a fiscal period's own `version`, it is null after an unfreeze. An open section has no rows and zero subtotals.", "required": [ "period", "starts_on", "ends_on", "status", "version", "rows", "subtotals" ], "properties": { "period": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])(-[12])?$", "example": "2026-09-1" }, "starts_on": { "type": "string", "format": "date", "example": "2026-09-01" }, "ends_on": { "type": "string", "format": "date", "example": "2026-09-15" }, "status": { "type": "string", "example": "closed", "enum": [ "open", "in_review", "closed" ] }, "version": { "type": "integer", "example": 1, "nullable": true, "minimum": 1 }, "rows": { "description": "By Book Date; within a day, invoices, then credit notes, then debit notes, then the practiced VAT withholdings printed on their own rows; then by number in natural order (a withholding's certificate number, then the number of the purchase it affects). `row_type` tells the kinds apart. Empty while the period is open.", "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/PurchaseBookDocumentRow" }, { "$ref": "#/components/schemas/PurchaseBookPracticedVatWithholdingRow" } ] } }, "subtotals": { "$ref": "#/components/schemas/PurchaseBookAmounts" } }, "type": "object" }, "PurchaseBookDocumentRow": { "description": "One declared purchase invoice (FAC), supplier credit note (NC) or supplier debit note (ND). `row_type` tells it apart from its sibling kind, `practiced_vat_withholding`. Its Registration Date places it in the period that contains that date, unless it is late; its emission date may fall in an earlier month. A credit note's amounts are negative. A late document is declared in the period that froze it and keeps its original dates. When the same Declared Set declares the practiced VAT withholding on it, the row shows its certificate and `amounts.withheld_vat`; otherwise both certificate fields are null and the VAT withheld is 0.00.", "required": [ "row_type", "sequence", "book_date", "registration_date", "document_date", "document_type", "document_id", "provider", "document_number", "control_number", "affected_document_number", "affected_control_number", "affected_document_id", "late", "withholding_certificate_number", "withholding_certificate_id", "amounts" ], "properties": { "row_type": { "type": "string", "example": "document", "enum": [ "document" ] }, "sequence": { "description": "The row's position in the month, across its sections; a refreeze may renumber it.", "type": "integer", "example": 1, "minimum": 1 }, "book_date": { "description": "The date the book orders the row by: its Registration Date.", "type": "string", "format": "date", "example": "2026-09-07" }, "registration_date": { "description": "The day the purchase was registered. It decides the row's period, except for a late document, which keeps this date and appears in the later period whose Declared Set declared it.", "type": "string", "format": "date", "example": "2026-09-07" }, "document_date": { "description": "The provider's emission date.", "type": "string", "format": "date", "example": "2026-09-07" }, "document_type": { "type": "string", "example": "FAC", "enum": [ "FAC", "NC", "ND" ] }, "document_id": { "type": "string", "format": "uuid" }, "provider": { "$ref": "#/components/schemas/PurchaseBookProvider" }, "document_number": { "description": "The provider's invoice number; null when it was never captured.", "type": "string", "example": "FAC-FC01", "nullable": true }, "control_number": { "type": "string", "example": "00-FC01", "nullable": true }, "affected_document_number": { "description": "The number of the purchase a note affects; null for an invoice.", "type": "string", "example": null, "nullable": true }, "affected_control_number": { "type": "string", "example": null, "nullable": true }, "affected_document_id": { "description": "The ERP id of the purchase a note affects; null for an invoice.", "type": "string", "format": "uuid", "example": null, "nullable": true }, "late": { "type": "boolean", "example": false }, "withholding_certificate_number": { "description": "The certificate of the practiced VAT withholding the same set declares on this document.", "type": "string", "example": "20260900000001", "nullable": true }, "withholding_certificate_id": { "description": "The ERP id of that certificate, for navigation only; its detail requires backoffice.fiscal.withholdings.view.", "type": "string", "format": "uuid", "nullable": true }, "amounts": { "$ref": "#/components/schemas/PurchaseBookAmounts" } }, "type": "object" }, "PurchaseBookPracticedVatWithholdingRow": { "description": "One declared VAT withholding the company practiced whose purchase another Declared Set declared, printed on its own row on its trigger date. Only `amounts.withheld_vat` is not zero, and it is positive. A withholding declared in the same set as its purchase never prints here: it shows on that purchase's row. A late withholding is declared in the period that froze it and keeps its trigger date.", "required": [ "row_type", "sequence", "book_date", "certificate_date", "vat_withholding_id", "withholding_certificate_number", "withholding_certificate_id", "provider", "affected_document_number", "affected_control_number", "affected_document_id", "late", "amounts" ], "properties": { "row_type": { "type": "string", "example": "practiced_vat_withholding", "enum": [ "practiced_vat_withholding" ] }, "sequence": { "description": "The row's position in the month, across its sections; a refreeze may renumber it.", "type": "integer", "example": 2, "minimum": 1 }, "book_date": { "description": "The withholding's trigger date.", "type": "string", "format": "date", "example": "2026-09-17" }, "certificate_date": { "description": "The day its certificate was issued; the trigger date while it has none.", "type": "string", "format": "date", "example": "2026-09-25" }, "vat_withholding_id": { "description": "The ERP id of the practiced VAT withholding.", "type": "string", "format": "uuid" }, "withholding_certificate_number": { "description": "Null only for a withholding declared without its certificate.", "type": "string", "example": "20260900000077", "nullable": true }, "withholding_certificate_id": { "description": "The ERP id of its certificate, for navigation only; its detail requires backoffice.fiscal.withholdings.view.", "type": "string", "format": "uuid", "nullable": true }, "provider": { "$ref": "#/components/schemas/PurchaseBookProvider" }, "affected_document_number": { "description": "The number of the purchase it withholds on, as its certificate names it.", "type": "string", "example": "FAC-FC02", "nullable": true }, "affected_control_number": { "type": "string", "example": "00-FC02", "nullable": true }, "affected_document_id": { "description": "The ERP id of the purchase invoice it withholds on.", "type": "string", "format": "uuid" }, "late": { "type": "boolean", "example": false }, "amounts": { "$ref": "#/components/schemas/PurchaseBookAmounts" } }, "type": "object" }, "PurchaseBookProvider": { "description": "The provider as the purchase froze it, or as its certificate names it on a withholding row; each part is null when none was frozen.", "required": [ "document_type", "document_number", "legal_name", "vat_taxpayer_type" ], "properties": { "document_type": { "type": "string", "example": "rif", "nullable": true, "enum": [ "rif", "cedula", "passport", null ] }, "document_number": { "type": "string", "example": "J-00123072-6", "nullable": true }, "legal_name": { "type": "string", "example": "Proveedor PA C.A.", "nullable": true }, "vat_taxpayer_type": { "type": "string", "example": "ordinary", "nullable": true, "enum": [ "ordinary", "formal", "non_taxpayer", null ] } }, "type": "object" }, "PurchaseBookAmounts": { "description": "The book's amount columns as signed decimal strings in bolívares, identical for a row, a section's subtotals and the summary. `total_with_vat` is the sum of every other column but `withheld_vat`. `non_creditable` is the VAT without right to fiscal credit, classified by the deductibility frozen with each declared row: such a row moves its `vat_general_tax`, `vat_reduced_tax` and `vat_additional_tax` into `non_creditable` and prints them as 0.00, while its bases stay in the `vat_*_base` columns. A row declared before that flag existed keeps its VAT as credit. `withheld_vat` comes only from practiced VAT withholdings, on their purchase's row or on their own.", "required": [ "total_with_vat", "exempt", "exonerated", "not_subject", "export", "other", "non_creditable", "vat_general_base", "vat_general_tax", "vat_reduced_base", "vat_reduced_tax", "vat_additional_base", "vat_additional_tax", "withheld_vat" ], "properties": { "total_with_vat": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "11600.00" }, "exempt": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "0.00" }, "exonerated": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "0.00" }, "not_subject": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "0.00" }, "export": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "0.00" }, "other": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "0.00" }, "non_creditable": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "0.00" }, "vat_general_base": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "10000.00" }, "vat_general_tax": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "1600.00" }, "vat_reduced_base": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "0.00" }, "vat_reduced_tax": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "0.00" }, "vat_additional_base": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "0.00" }, "vat_additional_tax": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "0.00" }, "withheld_vat": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "1200.00" } }, "type": "object" }, "PurchaseBookProblem": { "description": "A refusal of the Purchase Book: invalid_fiscal_book_month (422) or company_not_found (404).", "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string", "example": "<2026-13> no es un mes; se esperaba YYYY-MM, por ejemplo 2026-09" }, "error_code": { "type": "string", "example": "invalid_fiscal_book_month", "enum": [ "invalid_fiscal_book_month", "company_not_found" ] }, "errors": { "type": "object", "example": null, "nullable": true } }, "type": "object" }, "PurchaseBookExportProblem": { "description": "A 422 refusal of the Purchase Book's Excel export, before any attachment: invalid_fiscal_book_month, or purchase_book_excel_precision_exceeded when some row, subtotal or summary amount exceeds 9999999999999.99 in absolute value or would not keep its cents in Excel; the book itself stays exact in showPurchaseBook.", "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string", "example": "No se puede exportar el libro de compras a Excel sin perder precisión. Consulta las cifras exactas en pantalla." }, "error_code": { "type": "string", "example": "purchase_book_excel_precision_exceeded", "enum": [ "invalid_fiscal_book_month", "purchase_book_excel_precision_exceeded" ] }, "errors": { "type": "object", "example": null, "nullable": true } }, "type": "object" }, "PurchaseBookUnauthenticated": { "description": "The authentication middleware's refusal, returned before the controller runs.", "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" }, "PurchaseBookForbidden": { "description": "The route's can: middleware refusal (bootstrap/app.php normalizes it to the problem envelope).", "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string", "example": "Forbidden" }, "status": { "type": "integer", "example": 403 }, "detail": { "type": "string", "example": "You do not have permission to access this resource." }, "error_code": { "type": "string", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true } }, "type": "object" }, "PurchaseBookAccessRefused": { "description": "The company access or tenant membership middleware refusal; only tenant membership names a reason.", "required": [ "title", "status", "detail" ], "properties": { "title": { "type": "string", "example": "Forbidden" }, "status": { "type": "integer", "example": 403 }, "detail": { "type": "string", "example": "You do not have access to this company" }, "reason": { "description": "Present when tenant membership refuses the request", "type": "string" } }, "type": "object" }, "FiscalReceivedWithholding": { "description": "A Received Withholding (MER-3692, MER-3694, MER-3706, ADR 0190, 0194): the VAT a client that is a special taxpayer, or the ISLR a client that is an ISLR withholding agent, withheld from the sales invoices it paid, and a client's VAT also from its approved debit notes (ADR 0371). Each invoice it covers was relieved by `relieved_document` in its Document Currency, without any collection. Registered with the client's certificate its entry debits the kind's supported account, `vat_withholding_supported` (1.3.03.) or `islr_withholding_supported` (1.3.04.), against the receivable; reported without it, `reported_withholding_pending` (1.3.05.), until the certificate supports it and moves it to the kind's supported account; voided, every invoice got its debt back and every entry it posted was reversed. An adjustment of a VAT withholding (MER-3697, ADR 0263) is a row of its own that names the supported original it corrects in `corrects_id`, with negative amounts: it gives part of the withholding back to each invoice and reverses that share of 1.3.03. Only a VAT withholding is reviewed and adjusted. Every amount follows `^-?\\d+\\.\\d{2}$`.", "required": [ "id", "client_id", "kind", "status", "registered_as", "corrects_id", "certificate_number", "certificate_date", "received_on", "certificate_received_on", "eligibility_period", "legal_amount_ves", "registered_by_user_id", "registered_by_api_key_id", "registered_at", "voiding", "review", "supportable", "voidable", "adjustable", "lines" ], "properties": { "id": { "description": "The id the client generated (UUIDv7), which makes registering idempotent.", "type": "string", "format": "uuid", "example": "0199e0a0-0000-7000-8000-000000000101" }, "client_id": { "description": "The client that withheld.", "type": "string", "format": "uuid" }, "client_name": { "description": "The client's legal name, else its name (MER-3696). Present on the list and on `GET {id}`, null when the company does not keep that client; absent from the answers of register, support and void, so refetch the list after a write.", "type": "string", "example": "Distribuidora Andina, C.A.", "nullable": true }, "kind": { "description": "What was withheld: `vat` from the invoices' VAT, `islr` from their taxable base; treat a kind you do not know as another withholding tax.", "type": "string", "enum": [ "vat", "islr" ] }, "status": { "description": "Where it stands now: `reported`, the client reported it and its certificate is awaited, no fiscal credit yet; `supported`, the certificate is in hand; `voided`, every invoice it covered got its debt back. Treat a status you do not know as neither supportable nor voidable.", "type": "string", "enum": [ "reported", "supported", "voided" ] }, "registered_as": { "description": "How it was registered, which never changes: `supported` with its certificate, `reported` without it.", "type": "string", "enum": [ "reported", "supported" ] }, "corrects_id": { "description": "The supported original an adjustment corrects (MER-3697); null on an original. An adjustment's amounts are negative, its `review` null and its `adjustable` false.", "type": "string", "format": "uuid", "nullable": true }, "certificate_number": { "description": "The client's certificate number as its kind reads it (MER-4197): a `vat` one is `AAAAMM` and an eight-digit counter; an `islr` one may carry the client's own numbering, up to 30 characters with single inner spaces, letters and symbols included, that need not follow `AAAAMM` + 8. Null while reported; a voided one keeps it.", "type": "string", "example": "20260900000123", "nullable": true, "maxLength": 30 }, "certificate_date": { "description": "The day the certificate is dated. Null while reported.", "type": "string", "format": "date", "example": "2026-09-05", "nullable": true }, "received_on": { "description": "The day the company received the withholding, reported or with its certificate, the day its registration is dated.", "type": "string", "format": "date", "example": "2026-09-05" }, "certificate_received_on": { "description": "The day the certificate was received, the day a support's reclassification is dated: `received_on` when registered supported; null while reported.", "type": "string", "format": "date", "example": "2026-09-05", "nullable": true }, "eligibility_period": { "description": "The month it is eligible in, the month its certificate was received (V08); null while reported.", "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$", "example": "2026-09", "nullable": true }, "legal_amount_ves": { "description": "The bolívars withheld over every invoice it covers, signed: negative on an adjustment, which gives them back.", "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "1200.00" }, "registered_by_user_id": { "description": "Who registered it; null outside a user's request.", "type": "string", "example": "42", "nullable": true }, "registered_by_api_key_id": { "description": "The API key that registered it; null for a browser session.", "type": "string", "nullable": true }, "registered_at": { "description": "ISO 8601 in UTC.", "type": "string", "format": "date-time", "example": "2026-09-05T20:00:00+00:00" }, "voiding": { "description": "Why, when and by whom it was voided; null while it stands.", "required": [ "reason", "voided_at", "voided_on", "voided_by_user_id", "voided_by_api_key_id" ], "properties": { "reason": { "type": "string", "example": "Comprobante emitido a otra factura", "maxLength": 500 }, "voided_at": { "description": "ISO 8601 in UTC.", "type": "string", "format": "date-time", "example": "2026-11-06T14:00:00+00:00" }, "voided_on": { "description": "The company's day it was voided, the day its reversals are dated.", "type": "string", "format": "date", "example": "2026-11-06" }, "voided_by_user_id": { "type": "string", "example": "42", "nullable": true }, "voided_by_api_key_id": { "description": "The API key that voided it; null for a browser session.", "type": "string", "nullable": true } }, "type": "object", "nullable": true, "additionalProperties": false }, "supportable": { "description": "Whether its certificate may support it now, the rule the server applies: true only while reported; offer «Soportar» only when true and the user may review withholdings.", "type": "boolean" }, "review": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/FiscalReceivedWithholdingReview" } ] }, "voidable": { "description": "Whether it may be voided now, the rule the server applies: true while reported or supported and no adjustment of it stands; offer «Anular» only when true and the user may review withholdings.", "type": "boolean" }, "adjustable": { "description": "Whether the client's adjustment may correct it now (MER-3697), the rule the server applies: a supported VAT original still withholding something of an invoice, never an ISLR one; offer «Registrar ajuste» only when true and the user may review withholdings.", "type": "boolean" }, "lines": { "description": "Each sales invoice it covers, in request order, with what that invoice gave up in each book.", "type": "array", "items": { "$ref": "#/components/schemas/FiscalReceivedWithholdingLine" } } }, "type": "object" }, "FiscalReceivedWithholdingLine": { "description": "One sales invoice, or debit note of a `vat` withholding, a received withholding relieved, measured against the basis of the withholding's `kind` (MER-3706): exactly that pair is filled and the other is null. The legal amount in bolívars wins (ADR 0126): a `vat` line's document gave up the same share of its VAT, `vat_document × legal_amount_ves ÷ vat_ves`; an `islr` line's the same share of its taxable base, `base_document × legal_amount_ves ÷ base_ves`; either rounded half-up once. The functional book gave up the legal amount's value.", "required": [ "position", "sales_invoice_id", "legal_amount_ves", "vat_ves", "vat_document", "base_ves", "base_document", "document_currency", "relieved_document", "functional_currency", "legal_amount_functional", "relieved_functional", "reporting_currency", "relieved_reporting", "adjustable_ves" ], "properties": { "position": { "description": "Its place in the request, which a refusal names as `lines.N`.", "type": "integer", "example": 0, "minimum": 0 }, "sales_invoice_id": { "type": "string", "format": "uuid" }, "sales_invoice_code": { "description": "The code of the invoice or debit note, the label of its link (MER-3696). Present on the list and on `GET {id}`, null when the company does not keep that invoice; absent from the answers of register, support and void.", "type": "string", "example": "FV-0002", "nullable": true }, "sales_invoice_kind": { "description": "Which document the line names, so which record opens it: the invoice detail answers 404 on a debit note (ADR 0371). Present on the list and on `GET {id}`, null when the company does not keep that document; absent from the answers of register, support and void.", "type": "string", "example": "regular", "nullable": true, "enum": [ "regular", "debit_note", null ] }, "legal_amount_ves": { "description": "The bolívars the certificate withheld from this invoice's VAT (`vat`) or taxable base (`islr`); negative on an adjustment's line.", "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "1200.00" }, "vat_ves": { "description": "The invoice's VAT in bolívars; null on an `islr` line.", "type": "string", "pattern": "^\\d+\\.\\d{2}$", "example": "1600.00", "nullable": true }, "vat_document": { "description": "The invoice's VAT in its Document Currency; null on an `islr` line.", "type": "string", "pattern": "^\\d+\\.\\d{2}$", "example": "1600.00", "nullable": true }, "base_ves": { "description": "The invoice's taxable base in bolívars, every tax group's base net of discount and without VAT; null on a `vat` line.", "type": "string", "pattern": "^\\d+\\.\\d{2}$", "example": null, "nullable": true }, "base_document": { "description": "The invoice's taxable base in its Document Currency; null on a `vat` line.", "type": "string", "pattern": "^\\d+\\.\\d{2}$", "example": null, "nullable": true }, "document_currency": { "type": "string", "example": "VES" }, "relieved_document": { "description": "What the invoice's balance gave up, in its Document Currency; negative on an adjustment's line, which restored it.", "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "1200.00" }, "functional_currency": { "type": "string", "example": "VES" }, "legal_amount_functional": { "description": "The legal amount's value in the functional book, what the kind's supported account carries there; negative on an adjustment's line.", "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "1200.00" }, "relieved_functional": { "description": "What the receivable gave up in the functional book; negative on an adjustment's line.", "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "1200.00" }, "reporting_currency": { "type": "string", "example": "USD" }, "relieved_reporting": { "description": "What the receivable gave up in the reporting book; negative on an adjustment's line.", "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "10.91" }, "adjustable_ves": { "description": "The bolívars an adjustment may still give back of this invoice (MER-3697): what the line withheld net of the standing adjustments; `0.00` when the withholding is not adjustable, as an ISLR one never is. Cap the adjustment form's line at it.", "type": "string", "pattern": "^\\d+\\.\\d{2}$", "example": "1200.00" } }, "type": "object", "additionalProperties": false }, "FiscalReceivedWithholdingReview": { "description": "The review an approved credit note asked of a standing received VAT withholding (MER-3697, rule 881): the note left the invoice less VAT in bolívars than the withholding covers at the percentage it withheld. Only the latest note is kept. Null on the row when it was never flagged, always on an ISLR withholding.", "required": [ "state", "credit_note_id", "sales_invoice_id", "vat_remaining_ves", "excess_ves", "resolution", "resolved_by_id" ], "properties": { "state": { "description": "`pending` until an adjustment resolves it or the withholding is voided; `resolved` after. Voiding the adjustment that resolved it, or a later note leaving an excess, makes it `pending` again.", "type": "string", "enum": [ "pending", "resolved" ] }, "credit_note_id": { "description": "The latest credit note that flagged it.", "type": "string", "format": "uuid" }, "credit_note_code": { "description": "The note's code, on the list and on `GET {id}` only; null when the company does not keep it; absent from the write answers.", "type": "string", "example": "NC-0001", "nullable": true }, "sales_invoice_id": { "description": "The invoice the note was on, one the withholding covers.", "type": "string", "format": "uuid" }, "sales_invoice_code": { "description": "That invoice's code, on the list and on `GET {id}` only; null when the company does not keep it; absent from the write answers.", "type": "string", "example": "FV-0002", "nullable": true }, "vat_remaining_ves": { "description": "The VAT in bolívars the approved notes left that invoice when the latest note was approved.", "type": "string", "pattern": "^\\d+\\.\\d{2}$", "example": "800.00" }, "excess_ves": { "description": "What it still withholds of that invoice, net of its standing adjustments, beyond `vat_remaining_ves × legal ÷ vat_ves` rounded half-up once; derived now, never below `0.00`, and `0.00` once voided. Pre-fill the adjustment with its negative.", "type": "string", "pattern": "^\\d+\\.\\d{2}$", "example": "600.00" }, "resolution": { "description": "How a resolved review was resolved: `adjusted` by the adjustment `resolved_by_id` names, or `voided` with the withholding; null while pending.", "type": "string", "nullable": true, "enum": [ "adjusted", "voided", null ] }, "resolved_by_id": { "description": "The adjustment that resolved it; null while pending or when voided.", "type": "string", "format": "uuid", "nullable": true } }, "type": "object", "additionalProperties": false }, "FiscalReceivedWithholdingsMeta": { "description": "How the list of received withholdings pages (MER-3694), how many each status and each kind holds (MER-3696, MER-3706) and the clients to filter by (MER-3696).", "required": [ "total", "per_page", "current_page", "last_page", "counts", "kind_counts", "clients" ], "properties": { "total": { "description": "The withholdings every filter matches, the same count as `summary.count`.", "type": "integer", "example": 1, "minimum": 0 }, "per_page": { "type": "integer", "example": 50, "maximum": 100, "minimum": 1 }, "current_page": { "type": "integer", "example": 1, "minimum": 1 }, "last_page": { "description": "At least 1, even when nothing matches.", "type": "integer", "example": 1, "minimum": 1 }, "counts": { "description": "The withholdings of each status under every filter but `status` and `as_of`, `kind` and `review` included; the known statuses are always named, at zero when empty, and a status a later slice adds is listed too. With `eligibility_period`, `reported` is always 0: a reported withholding has no eligibility period. `review_pending`, always present, counts the ones pending review under every filter but `review`, `kind` included (MER-3697). An adjustment counts under its status.", "required": [ "reported", "supported", "voided", "review_pending" ], "properties": { "reported": { "type": "integer", "example": 1, "minimum": 0 }, "supported": { "type": "integer", "example": 1, "minimum": 0 }, "voided": { "type": "integer", "example": 0, "minimum": 0 }, "review_pending": { "type": "integer", "example": 1, "minimum": 0 } }, "type": "object", "additionalProperties": { "type": "integer" } }, "kind_counts": { "description": "The withholdings of each kind under every filter but `kind` (MER-3706), `status`, `as_of` and `review` included; both kinds are always named, at zero when empty, and a kind a later slice adds is listed too. «Todos» is their sum.", "required": [ "vat", "islr" ], "properties": { "vat": { "type": "integer", "example": 1, "minimum": 0 }, "islr": { "type": "integer", "example": 0, "minimum": 0 } }, "type": "object", "additionalProperties": { "type": "integer" } }, "clients": { "description": "Every client of the company with at least one received withholding, whatever the filters, by name, nameless ones last, then by id: the options of the client filter.", "type": "array", "items": { "required": [ "id", "name" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "description": "The client's legal name, else its name; null when the company does not keep that client.", "type": "string", "example": "Distribuidora Andina, C.A.", "nullable": true } }, "type": "object", "additionalProperties": false } } }, "type": "object", "additionalProperties": false }, "FiscalReceivedWithholdingsSummary": { "description": "Every withholding the filters match, over every page (MER-3694): with `as_of`, the pending read of that cut-off day.", "required": [ "count", "total_bs" ], "properties": { "count": { "type": "integer", "example": 1, "minimum": 0 }, "total_bs": { "description": "The bolívars they withheld, `0.00` when none matches: a signed net, an adjustment counts as a row and subtracts (MER-3697), so it can be negative.", "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "1200.00" } }, "type": "object", "additionalProperties": false }, "FiscalReceivedWithholdingRegistration": { "description": "A received withholding as its registration answers it, with what it warns about.", "allOf": [ { "$ref": "#/components/schemas/FiscalReceivedWithholding" }, { "required": [ "warnings" ], "properties": { "warnings": { "description": "What the registration flags without refusing it, always an array: `client_not_special_taxpayer` only on a `vat` withholding, when the client was not a special taxpayer when an invoice it withheld from was emitted, so an `islr` one never warns it; `certificate_number_not_digital_format` only on a supported `islr` one whose certificate number does not follow `AAAAMM` + 8 (MER-4197). Empty on a replay. Treat a warning you do not know as informational.", "type": "array", "items": { "type": "string", "enum": [ "client_not_special_taxpayer", "certificate_number_not_digital_format" ] } } }, "type": "object" } ] }, "SalesBookLedgerCheck": { "description": "A month's Sales Book checked against the ledger (MER-3841, PRD MER-2724). When `available` is false, `unavailable_reason` says why, the four totals are null and both lists are empty; otherwise `unavailable_reason` is null and the totals are signed decimal strings in bolívares with `book_vat − ledger_vat = explained + unexplained`.", "required": [ "month", "currency", "available", "unavailable_reason", "book_vat", "ledger_vat", "explained", "unexplained", "differences", "other_movements" ], "properties": { "month": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$", "example": "2026-09" }, "currency": { "type": "string", "example": "VES", "enum": [ "VES" ] }, "available": { "description": "Whether the company's functional book can be checked against the book; never null.", "type": "boolean", "example": true }, "unavailable_reason": { "description": "Why the check is not available: the company's functional currency is not VES. Null when it is available.", "type": "string", "example": null, "nullable": true, "enum": [ "functional_currency_not_ves", null ] }, "book_vat": { "description": "The general, reduced and additional VAT of every invoice and note of the month's declared sections, late rows included.", "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "4640.00", "nullable": true }, "ledger_vat": { "description": "Credit − debit of the month's entries that link a sales invoice or note, on the accounts of the company's VAT-kind taxes, in the functional book.", "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "4640.00", "nullable": true }, "explained": { "description": "The signed sum of the differences whose cause is not `unexplained`.", "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "0.00", "nullable": true }, "unexplained": { "description": "The signed sum of the `unexplained` differences; opposite ones may net to 0.00.", "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "0.00", "nullable": true }, "differences": { "description": "Every document whose two amounts differ: `unexplained` first, then `not_yet_declared`, `late` and `reversal_in_other_month`; then invoices, credit notes and debit notes; then by number in natural order, a document without one last.", "type": "array", "items": { "$ref": "#/components/schemas/SalesBookLedgerDifference" } }, "other_movements": { "description": "Every other entry on the output VAT accounts in the month, one per entry, account and day, by date, entry code and account code. Informative only: never in `ledger_vat` nor in the differences.", "type": "array", "items": { "$ref": "#/components/schemas/SalesBookLedgerOtherMovement" } } }, "type": "object" }, "SalesBookLedgerDifference": { "description": "A sales invoice (FAC), credit note (NC) or debit note (ND) whose declared output VAT differs from what the ledger posted for it in the month. `difference = book_vat − ledger_vat`, so a negative one means the ledger posted more; a credit note is negative on both sides. The document links as the book's rows do, by `document_type` and `document_id`.", "required": [ "document_type", "document_id", "document_number", "book_vat", "ledger_vat", "difference", "cause" ], "properties": { "document_type": { "type": "string", "example": "FAC", "enum": [ "FAC", "NC", "ND" ] }, "document_id": { "type": "string", "format": "uuid" }, "document_number": { "description": "The number it was declared with, in the month or in the month that declares it now; null when no current Declared Set declares it.", "type": "string", "example": "00000002", "nullable": true }, "book_vat": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "0.00" }, "ledger_vat": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "48.00" }, "difference": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "-48.00" }, "cause": { "description": "Only `unexplained` is not explained by how the books work; more causes may be added.", "type": "string", "example": "late", "enum": [ "late", "not_yet_declared", "reversal_in_other_month", "unexplained" ] } }, "type": "object" }, "SalesBookLedgerOtherMovement": { "description": "What one entry that links no sales invoice or note moved on one output VAT account on one day, credit − debit: a VAT settlement debiting it is negative. Its fields are the general ledger detail's, so it links as a ledger row does.", "required": [ "date", "transaction_id", "transaction_code", "transaction_type", "linkable_type", "linkable_id", "account_id", "account_code", "account_name", "amount" ], "properties": { "date": { "type": "string", "format": "date", "example": "2026-09-24" }, "transaction_id": { "type": "string", "format": "uuid" }, "transaction_code": { "type": "string", "example": "AS-000024" }, "transaction_type": { "type": "string", "example": "manual_entry.approved" }, "linkable_type": { "type": "string", "example": "manual_entry" }, "linkable_id": { "type": "string", "format": "uuid" }, "account_id": { "type": "string", "format": "uuid" }, "account_code": { "type": "string", "example": "2.2.01." }, "account_name": { "type": "string", "example": "IVA débito fiscal" }, "amount": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "-4560.00" } }, "type": "object" }, "SalesBook": { "description": "A month's Sales Book (MER-3839, ADR 0264, ADR 0265): the Company's header, one section per Fiscal Period of the month, oldest first, each adding up its rows in `subtotals`, and the `summary` adding up every section's subtotals, so an open section adds nothing. Every amount is in the bolívares `currency` names once.", "required": [ "month", "currency", "company", "sections", "summary" ], "properties": { "month": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$", "example": "2026-09" }, "currency": { "type": "string", "example": "VES", "enum": [ "VES" ] }, "company": { "$ref": "#/components/schemas/SalesBookCompany" }, "sections": { "description": "Oldest first: the month alone, or its first fortnight then its second for a special taxpayer.", "type": "array", "items": { "$ref": "#/components/schemas/SalesBookSection" } }, "summary": { "$ref": "#/components/schemas/SalesBookAmounts" } }, "type": "object" }, "SalesBookCompany": { "description": "The Company's current fiscal profile; both are null when it has none, and the book still renders.", "required": [ "legal_name", "rif" ], "properties": { "legal_name": { "type": "string", "example": "QA Fiscal Company, C.A.", "nullable": true }, "rif": { "type": "string", "example": "J-00000000-0", "nullable": true } }, "type": "object" }, "SalesBookSection": { "description": "One Fiscal Period's part of the book. `version` is the Declared Set version its rows come from, null while the period is open: never frozen, unfrozen or reopened. Unlike a fiscal period's own `version`, it is null after an unfreeze. An open section has no rows and zero subtotals.", "required": [ "period", "starts_on", "ends_on", "status", "version", "rows", "subtotals" ], "properties": { "period": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])(-[12])?$", "example": "2026-09-1" }, "starts_on": { "type": "string", "format": "date", "example": "2026-09-01" }, "ends_on": { "type": "string", "format": "date", "example": "2026-09-15" }, "status": { "type": "string", "example": "closed", "enum": [ "open", "in_review", "closed" ] }, "version": { "type": "integer", "example": 1, "nullable": true, "minimum": 1 }, "rows": { "description": "By Book Date; within a day, invoices and the day's Non-Taxpayer Daily Summary (at its first number), then credit notes, then debit notes, then received VAT withholdings; then by number in natural order (a withholding's certificate number, then the number of the invoice it affects). `row_type` tells the kinds apart. Empty while the period is open.", "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/SalesBookDocumentRow" }, { "$ref": "#/components/schemas/SalesBookNonTaxpayerDailySummaryRow" }, { "$ref": "#/components/schemas/SalesBookReceivedVatWithholdingRow" } ] } }, "subtotals": { "$ref": "#/components/schemas/SalesBookAmounts" } }, "type": "object" }, "SalesBookDocumentRow": { "description": "One declared sales invoice (FAC), credit note (NC) or debit note (ND). `row_type` tells it apart from its sibling kinds, `non_taxpayer_daily_summary` and `received_vat_withholding`. An active, on-time, numbered invoice whose buyer froze as a VAT non-taxpayer prints inside its day's Non-Taxpayer Daily Summary instead. A credit note's amounts are negative. A late document is declared in the period that froze it and keeps its original Book Date, which may fall in an earlier month. A cancelled document shows every amount at zero.", "required": [ "row_type", "sequence", "book_date", "document_date", "document_type", "document_id", "buyer", "document_number", "control_number", "affected_document_number", "affected_control_number", "affected_document_id", "late", "cancelled", "amounts" ], "properties": { "row_type": { "type": "string", "example": "document", "enum": [ "document" ] }, "sequence": { "description": "The row's position in the month, across its sections; a refreeze may renumber it.", "type": "integer", "example": 1, "minimum": 1 }, "book_date": { "type": "string", "format": "date", "example": "2026-09-02" }, "document_date": { "type": "string", "format": "date", "example": "2026-09-02" }, "document_type": { "type": "string", "example": "FAC", "enum": [ "FAC", "NC", "ND" ] }, "document_id": { "type": "string", "format": "uuid" }, "buyer": { "$ref": "#/components/schemas/SalesBookBuyer" }, "document_number": { "type": "string", "example": "00000001", "nullable": true }, "control_number": { "type": "string", "example": "00-00000001", "nullable": true }, "affected_document_number": { "description": "The number of the document a note affects; null for an invoice.", "type": "string", "example": null, "nullable": true }, "affected_control_number": { "type": "string", "example": null, "nullable": true }, "affected_document_id": { "description": "The ERP id of the document a note affects; null for an invoice.", "type": "string", "format": "uuid", "example": null, "nullable": true }, "late": { "type": "boolean", "example": false }, "cancelled": { "type": "boolean", "example": false }, "amounts": { "$ref": "#/components/schemas/SalesBookAmounts" } }, "type": "object" }, "SalesBookNonTaxpayerDailySummaryRow": { "description": "One day's Non-Taxpayer Daily Summary (BOOK-04): the day's active, on-time, numbered sales invoices whose buyer froze as a VAT non-taxpayer, as one row with the first and last number in natural order, how many it summarizes and their summed amounts. Credit and debit notes, cancelled and late invoices, and invoices whose buyer froze otherwise keep their own rows, so no document counts twice; the range may span a number it does not count, such as a cancelled invoice printed apart. A day without such invoices has no summary. It names no buyer and links no record.", "required": [ "row_type", "sequence", "book_date", "first_document_number", "last_document_number", "document_count", "amounts" ], "properties": { "row_type": { "type": "string", "example": "non_taxpayer_daily_summary", "enum": [ "non_taxpayer_daily_summary" ] }, "sequence": { "description": "The row's position in the month, across its sections; a refreeze may renumber it.", "type": "integer", "example": 3, "minimum": 1 }, "book_date": { "type": "string", "format": "date", "example": "2026-09-04" }, "fiscal_machine_serial": { "description": "Machine serial frozen with the declaration; absent for legacy sets and documents without a serial.", "type": "string", "nullable": true }, "first_document_number": { "type": "string", "example": "00000101" }, "last_document_number": { "type": "string", "example": "00000104" }, "document_count": { "description": "How many invoices it summarizes, not the width of the range.", "type": "integer", "example": 3, "minimum": 1 }, "amounts": { "$ref": "#/components/schemas/SalesBookAmounts" } }, "type": "object" }, "SalesBookReceivedVatWithholdingRow": { "description": "One declared line of a supported VAT withholding a customer practiced: a certificate over several invoices prints one row per invoice, and an adjustment prints its own rows with a negative amount. Only `amounts.withheld_vat` is not zero; the subtotals and the summary add it apart from sales. A reported withholding is never declared, so it never prints. A late withholding is declared in the period that froze it and keeps the day its certificate arrived.", "required": [ "row_type", "sequence", "book_date", "certificate_date", "received_withholding_id", "certificate_number", "buyer", "affected_document_number", "affected_control_number", "affected_document_id", "late", "amounts" ], "properties": { "row_type": { "type": "string", "example": "received_vat_withholding", "enum": [ "received_vat_withholding" ] }, "sequence": { "description": "The row's position in the month, across its sections; a refreeze may renumber it.", "type": "integer", "example": 4, "minimum": 1 }, "book_date": { "description": "The day its certificate was received.", "type": "string", "format": "date", "example": "2026-09-05" }, "certificate_date": { "type": "string", "format": "date", "example": "2026-09-05" }, "received_withholding_id": { "description": "The ERP id of the received withholding.", "type": "string", "format": "uuid" }, "certificate_number": { "type": "string", "example": "20260900000123" }, "buyer": { "$ref": "#/components/schemas/SalesBookBuyer" }, "affected_document_number": { "description": "The number of the invoice it withholds on.", "type": "string", "example": "00000002", "nullable": true }, "affected_control_number": { "type": "string", "example": "00-00000002", "nullable": true }, "affected_document_id": { "description": "The ERP id of the invoice it withholds on.", "type": "string", "format": "uuid" }, "late": { "type": "boolean", "example": false }, "amounts": { "$ref": "#/components/schemas/SalesBookAmounts" } }, "type": "object" }, "SalesBookBuyer": { "description": "The buyer as the document froze it; each part is null when the document froze none. An active, on-time, numbered invoice whose buyer froze as `non_taxpayer` prints inside its day's Non-Taxpayer Daily Summary, which names no buyer. On a withholding row, the customer as the withheld invoice froze it.", "required": [ "document_type", "document_number", "legal_name", "vat_taxpayer_type" ], "properties": { "document_type": { "type": "string", "example": "rif", "nullable": true, "enum": [ "rif", "cedula", "passport", null ] }, "document_number": { "type": "string", "example": "J-00123072-6", "nullable": true }, "legal_name": { "type": "string", "example": "Cliente A C.A.", "nullable": true }, "vat_taxpayer_type": { "type": "string", "example": "ordinary", "nullable": true, "enum": [ "ordinary", "formal", "non_taxpayer", null ] } }, "type": "object" }, "SalesBookAmounts": { "description": "The book's amount columns as signed decimal strings in bolívares, identical for a row, a section's subtotals and the summary. `total_with_vat` is the sum of the other columns but `withheld_vat`, which only `received_vat_withholding` rows carry, signed (negative for an adjustment); the subtotals and the summary add it apart from sales.", "required": [ "total_with_vat", "exempt", "exonerated", "not_subject", "export", "other", "vat_general_base", "vat_general_tax", "vat_reduced_base", "vat_reduced_tax", "vat_additional_base", "vat_additional_tax", "withheld_vat" ], "properties": { "total_with_vat": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "11600.00" }, "exempt": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "0.00" }, "exonerated": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "0.00" }, "not_subject": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "0.00" }, "export": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "0.00" }, "other": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "0.00" }, "vat_general_base": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "10000.00" }, "vat_general_tax": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "1600.00" }, "vat_reduced_base": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "0.00" }, "vat_reduced_tax": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "0.00" }, "vat_additional_base": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "0.00" }, "vat_additional_tax": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "0.00" }, "withheld_vat": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "0.00" } }, "type": "object" }, "SalesBookProblem": { "description": "A refusal of the Sales Book: invalid_fiscal_book_month (422) or company_not_found (404).", "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string", "example": "<2026-13> no es un mes; se esperaba YYYY-MM, por ejemplo 2026-09" }, "error_code": { "type": "string", "example": "invalid_fiscal_book_month", "enum": [ "invalid_fiscal_book_month", "company_not_found" ] }, "errors": { "type": "object", "example": null, "nullable": true } }, "type": "object" }, "SalesBookExportProblem": { "description": "A 422 refusal of the Sales Book's Excel export, before any attachment: invalid_fiscal_book_month, or sales_book_excel_precision_exceeded when some row, subtotal or summary amount exceeds 9999999999999.99 in absolute value or would not keep its cents in Excel; the book itself stays exact in showSalesBook.", "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string", "example": "No se puede exportar el libro de ventas a Excel sin perder precisión. Consulta las cifras exactas en pantalla." }, "error_code": { "type": "string", "example": "sales_book_excel_precision_exceeded", "enum": [ "invalid_fiscal_book_month", "sales_book_excel_precision_exceeded" ] }, "errors": { "type": "object", "example": null, "nullable": true } }, "type": "object" }, "SalesBookUnauthenticated": { "description": "The authentication middleware's refusal, returned before the controller runs.", "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" }, "SalesBookForbidden": { "description": "The route's can: middleware refusal (bootstrap/app.php normalizes it to the problem envelope).", "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string", "example": "Forbidden" }, "status": { "type": "integer", "example": 403 }, "detail": { "type": "string", "example": "You do not have permission to access this resource." }, "error_code": { "type": "string", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true } }, "type": "object" }, "SalesBookAccessRefused": { "description": "The company access or tenant membership middleware refusal; only tenant membership names a reason.", "required": [ "title", "status", "detail" ], "properties": { "title": { "type": "string", "example": "Forbidden" }, "status": { "type": "integer", "example": 403 }, "detail": { "type": "string", "example": "You do not have access to this company" }, "reason": { "description": "Present when tenant membership refuses the request", "type": "string" } }, "type": "object" }, "FiscalWithholdingCertificateSummary": { "description": "Certificate summary nested on a practised VAT or ISLR withholding list row.", "required": [ "id", "number", "issued_on", "status", "validation_locked", "delivery" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "0199c3a0-1111-7abc-9def-000000000001" }, "number": { "type": "string", "pattern": "^\\d{4}(0[1-9]|1[0-2])\\d{8}$", "example": "20260900000001" }, "issued_on": { "description": "The company's day it was issued on, in its time zone.", "type": "string", "format": "date", "example": "2026-09-24" }, "status": { "type": "string", "enum": [ "issued", "voided" ] }, "validation_locked": { "description": "true while the company's withholding certificates are not validated (pending the accountant's ruling, MER-2751): the certificate prints «NO VALIDADO» and a new delivery answers 422 withholding_certificate_delivery_locked. Read from the company on every request; the same for every certificate of the company.", "type": "boolean", "example": true }, "delivery": { "description": "When and how it reached the provider; null until recorded.", "required": [ "delivered_at", "channel" ], "properties": { "delivered_at": { "description": "ISO 8601 in UTC.", "type": "string", "format": "date-time", "example": "2026-09-24T14:30:00+00:00" }, "channel": { "type": "string", "enum": [ "email", "whatsapp", "in_person", "provider_portal" ] } }, "type": "object", "nullable": true, "additionalProperties": false } }, "type": "object", "additionalProperties": false }, "TaxDeclarationRemittanceLink": { "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid" } }, "type": "object" }, "TaxDeclarationVersion": { "required": [ "id", "company_id", "kind", "period", "period_type", "version", "replaces_id", "return_number", "filed_on", "payable_ves", "carried_excess_ves", "carried_withholdings_ves", "paid_on", "paid_ves", "payment_reference", "status", "notes", "created_by", "created_at", "updated_at", "remittances" ], "properties": { "id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "vat", "vat_withholding", "islr_withholding", "igtf_perceived" ] }, "period": { "type": "string", "example": "2026-09-1" }, "period_type": { "type": "string", "enum": [ "month", "fortnight" ] }, "version": { "type": "integer", "example": 1 }, "replaces_id": { "type": "string", "format": "uuid", "nullable": true }, "return_number": { "type": "string", "example": "12345678" }, "filed_on": { "type": "string", "format": "date", "example": "2026-09-24" }, "payable_ves": { "type": "string", "example": "0.00" }, "carried_excess_ves": { "type": "string", "example": "0.00", "nullable": true }, "carried_withholdings_ves": { "type": "string", "example": "0.00", "nullable": true }, "paid_on": { "type": "string", "format": "date", "nullable": true }, "paid_ves": { "type": "string", "nullable": true }, "payment_reference": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "filed", "paid", "replaced" ] }, "notes": { "type": "string", "nullable": true }, "created_by": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "remittances": { "type": "array", "items": { "$ref": "#/components/schemas/TaxDeclarationRemittanceLink" } } }, "type": "object" }, "TaxDeclarationDossier": { "required": [ "current", "versions" ], "properties": { "current": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/TaxDeclarationVersion" } ] }, "versions": { "type": "array", "items": { "$ref": "#/components/schemas/TaxDeclarationVersion" } } }, "type": "object" }, "TaxObligationWorkpaperLink": { "required": [ "type", "period", "kind" ], "properties": { "type": { "type": "string", "enum": [ "vat_workpaper", "withholding_workpaper" ] }, "period": { "type": "string", "example": "2026-10-1" }, "kind": { "type": "string", "example": null, "nullable": true, "enum": [ "vat_withholding", "islr_withholding", "igtf_perceived", null ] } }, "type": "object" }, "TaxObligationDeclarationLink": { "required": [ "id", "status" ], "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "filed", "paid" ] } }, "type": "object" }, "TaxObligation": { "required": [ "obligation", "period", "period_type", "regime", "due_on", "due_status", "status", "workpaper", "declaration" ], "properties": { "obligation": { "type": "string", "enum": [ "vat", "vat_withholding", "islr_withholding", "igtf_perceived" ] }, "period": { "type": "string", "example": "2026-10-1" }, "period_type": { "type": "string", "enum": [ "month", "fortnight" ] }, "regime": { "type": "string", "enum": [ "special", "ordinary" ] }, "due_on": { "type": "string", "format": "date", "example": "2026-10-21", "nullable": true }, "due_status": { "type": "string", "enum": [ "verified", "unverified", "not_in_calendar" ] }, "status": { "type": "string", "enum": [ "pending", "overdue", "filed", "paid" ] }, "workpaper": { "$ref": "#/components/schemas/TaxObligationWorkpaperLink" }, "declaration": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/TaxObligationDeclarationLink" } ] } }, "type": "object" }, "TaxObligationsResponse": { "required": [ "obligations", "reason" ], "properties": { "obligations": { "type": "array", "items": { "$ref": "#/components/schemas/TaxObligation" } }, "reason": { "type": "string", "example": null, "nullable": true, "enum": [ "company_fiscal_profile_missing", "tax_attributes_missing", null ] } }, "type": "object" }, "FiscalTaxUnit": { "required": [ "rule_id", "value_bs", "effective_from", "source_article", "matrix_rule_id", "matrix_version" ], "properties": { "rule_id": { "description": "The rule id an ISLR withholding snapshots for the unit it used. Stable across environments: derived from country and effective_from.", "type": "string", "format": "uuid", "example": "45192523-531e-533e-850b-8c083ad59409" }, "value_bs": { "description": "Value of one tax unit in bolívares (VES), as an exact scale-2 decimal string.", "type": "string", "pattern": "^\\d{1,10}\\.\\d{2}$", "example": "43.00" }, "effective_from": { "description": "First day the unit is in force.", "type": "string", "format": "date", "example": "2025-06-02" }, "source_article": { "type": "string", "example": "PA SNAT/2025/000048, GO 43.140", "maxLength": 120 }, "matrix_rule_id": { "description": "Fiscal rules matrix row that researched the unit.", "type": "string", "pattern": "^[A-Z]+-\\d{2}$", "example": "ISLR-03" }, "matrix_version": { "description": "Newest fiscal rules matrix version that changed the row the unit was researched from.", "type": "string", "example": "2026-09-20-research-3" } }, "type": "object", "additionalProperties": false }, "FiscalVatWithholdingRate": { "required": [ "rule_id", "code", "kind", "label", "percentage", "effective_from", "source_article", "matrix_rule_id", "matrix_version" ], "properties": { "rule_id": { "description": "The rule id a withholding snapshots. Stable across environments: derived from country, code and effective_from.", "type": "string", "format": "uuid", "example": "9316d4fb-a7b7-5ebe-a3f3-40fc0b6d8556" }, "code": { "description": "Stable rule code embedding its article and numeral; `standard` for the general rate.", "type": "string", "pattern": "^[a-z0-9_]{1,64}$", "example": "standard" }, "kind": { "description": "standard: art. 4 general rate; full: an art. 5 cause for 100 %; exclusion: an art. 3 exclusion for 0 %.", "type": "string", "enum": [ "standard", "full", "exclusion" ] }, "label": { "description": "Spanish label for the reason selector.", "type": "string", "example": "Retención general del 75 % del IVA causado", "maxLength": 120 }, "percentage": { "description": "Share of the VAT charged that is withheld, as an exact scale-2 decimal string.", "type": "string", "pattern": "^\\d{1,3}\\.\\d{2}$", "example": "75.00" }, "effective_from": { "description": "First day the rule applies to taxable events.", "type": "string", "format": "date", "example": "2025-08-01" }, "source_article": { "type": "string", "example": "PA SNAT/2025/000054 art. 4", "maxLength": 120 }, "matrix_rule_id": { "description": "Fiscal rules matrix row that researched the rule.", "type": "string", "pattern": "^[A-Z]+-\\d{2}$", "example": "WHV-03" }, "matrix_version": { "description": "Fiscal rules matrix version the rule was researched in.", "type": "string", "example": "2026-09-20-research-3" } }, "type": "object", "additionalProperties": false }, "FiscalVatWithholding": { "description": "A VAT withholding the company practised on a purchases invoice (MER-3107): its amounts in the shape of the approval's `vat_withholding_proposal`, the rule it snapshots with its label, the certificate that certifies or certified it, the invoice and provider it was practised on (MER-3110), its voiding, the earlier trigger date a prior payment suggests and the remittance that paid it to SENIAT (MER-3111).", "required": [ "id", "purchases_invoice_id", "invoice_code", "invoice_number", "document_kind", "provider_id", "provider_name", "status", "voidable", "remittable", "remittance", "trigger_date", "fortnight", "trigger_date_superseded", "suggested_trigger_date", "suggested_fortnight", "rule_id", "rule_code", "rule_label", "percentage", "reason", "vat_base_ves", "withheld_amount_ves", "relief_document", "certificate", "voiding" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "0199c3a0-2222-7abc-9def-000000000001" }, "purchases_invoice_id": { "type": "string", "format": "uuid", "example": "0199c3a0-3333-7abc-9def-000000000001" }, "invoice_code": { "description": "The code of the purchases invoice or Supplier Debit Note withheld from, whose id opens its record as `document_kind` says; null if Purchases does not name it.", "type": "string", "example": "PIN26000007", "nullable": true }, "invoice_number": { "description": "The number the provider printed on the invoice.", "type": "string", "example": "00000107", "nullable": true }, "document_kind": { "description": "Which purchase was withheld from, so the row opens the right record (MER-5386): `invoice` (an invoice or an opening document) or `debit_note` (a Supplier Debit Note, whose code is `NDP…`); null if Purchases does not name it.", "type": "string", "example": "invoice", "nullable": true, "enum": [ "invoice", "debit_note" ] }, "provider_id": { "type": "string", "format": "uuid", "example": "0199c3a0-4444-7abc-9def-000000000001" }, "provider_name": { "description": "The provider's legal name frozen on the invoice, else its current legal name or name.", "type": "string", "example": "Distribuidora Andina, C.A.", "nullable": true }, "status": { "description": "`certified` once its certificate is issued; a 0 % exclusion withholds nothing and stays `determined`; `remitted` once a remittance paid it to SENIAT (MER-3111), and `certified` again if that remittance is voided; `voided` once voided, by its own request or by cancelling its invoice, which a remitted one never is. Treat a status you do not know as not current.", "type": "string", "enum": [ "determined", "certified", "remitted", "voided" ] }, "voidable": { "description": "Whether it may be voided now, the rule the server applies (MER-3110): false once remitted or voided; offer «Anular» only when true and the user may review withholdings.", "type": "boolean" }, "remittable": { "description": "Whether a remittance may pay it now, the rule the server applies (MER-3111): true only while `certified`; select it for «Registrar enteramiento» only when true.", "type": "boolean" }, "remittance": { "description": "The remittance not voided that paid it to SENIAT (MER-3111), whose id opens `GET fiscal/withholding-remittances/{id}` and is what «Anular enteramiento» voids; null while none stands.", "required": [ "id", "remitted_on", "bank_reference", "amount", "status" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "0199e0a0-0000-7000-8000-000000000025" }, "remitted_on": { "description": "The day it was paid to SENIAT.", "type": "string", "format": "date", "example": "2026-09-24" }, "bank_reference": { "type": "string", "example": "SIM-Q1-IVA-25", "maxLength": 120 }, "amount": { "description": "The whole remittance's amount, not this row's.", "required": [ "amount", "currency" ], "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "example": "2760.00" }, "currency": { "type": "string", "example": "VES" } }, "type": "object", "additionalProperties": false }, "status": { "description": "Only the remittance that stands is shown.", "type": "string", "enum": [ "recorded" ] } }, "type": "object", "nullable": true, "additionalProperties": false }, "trigger_date": { "description": "The invoice's registration date, the day it was determined. Never re-dated.", "type": "string", "format": "date", "example": "2026-09-09" }, "fortnight": { "description": "The fortnight of its trigger date, which is when it is declared. Never re-dated.", "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])-[12]$", "example": "2026-09-1" }, "trigger_date_superseded": { "description": "A payment dated before the registration suggests an earlier trigger date (ADR 0189): flag it for the accounting review.", "type": "boolean" }, "suggested_trigger_date": { "description": "The earliest such payment's day; null unless flagged.", "type": "string", "format": "date", "example": "2026-09-05", "nullable": true }, "suggested_fortnight": { "description": "The fortnight of the suggested day; null unless flagged.", "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])-[12]$", "example": "2026-09-1", "nullable": true }, "rule_id": { "description": "The VAT withholding rule it snapshots (ADR 0192).", "type": "string", "format": "uuid", "example": "9316d4fb-a7b7-5ebe-a3f3-40fc0b6d8556" }, "rule_code": { "type": "string", "example": "standard", "maxLength": 64 }, "rule_label": { "description": "The Spanish label of the catalog rule, which is also the label of its reason.", "type": "string", "example": "Retención general del 75 % del IVA causado", "maxLength": 120 }, "percentage": { "description": "The share of the VAT withheld, a decimal string.", "type": "string", "pattern": "^\\d{1,3}\\.\\d{2}$", "example": "75.00" }, "reason": { "description": "The legal ground of a cause for 100 % or an exclusion at 0 %, whose code is always `rule_code`; null under the standard rule.", "required": [ "code", "note" ], "properties": { "code": { "type": "string", "example": "art3_n1_not_subject_exempt_or_exonerated", "maxLength": 64 }, "note": { "description": "The evidence note given at approval.", "type": "string", "example": "Operación exenta de IVA.", "maxLength": 500 } }, "type": "object", "nullable": true, "additionalProperties": false }, "vat_base_ves": { "description": "The VAT charged that the percentage applied to, in bolívars.", "type": "string", "pattern": "^\\d+\\.\\d{2}$", "example": "2080.00" }, "withheld_amount_ves": { "description": "The legal amount withheld, in bolívars.", "type": "string", "pattern": "^\\d+\\.\\d{2}$", "example": "1560.00" }, "relief_document": { "description": "What it relieved of the supplier's debt, in the invoice's Document Currency: the invoice's `withheld_amount`.", "required": [ "amount", "currency" ], "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "example": "12.00" }, "currency": { "type": "string", "example": "USD" } }, "type": "object", "additionalProperties": false }, "certificate": { "description": "The certificate that certifies it, or certified it once voided (it keeps its number), whose id opens `GET fiscal/withholding-certificates/{id}`; null while it has none, as for a 0 % exclusion.", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/FiscalWithholdingCertificateSummary" } ] }, "voiding": { "description": "Why, when and by whom it was voided; null while it stands.", "required": [ "voided_at", "reason", "voided_by_user_id" ], "properties": { "voided_at": { "description": "ISO 8601 in UTC.", "type": "string", "format": "date-time", "example": "2026-10-08T14:30:00+00:00" }, "reason": { "type": "string", "example": "Factura cancelada", "maxLength": 500 }, "voided_by_user_id": { "type": "string", "example": "42", "nullable": true } }, "type": "object", "nullable": true, "additionalProperties": false } }, "type": "object", "additionalProperties": false }, "FiscalVatWithholdingsMeta": { "description": "How the list of VAT withholdings pages (MER-3110).", "required": [ "total", "per_page", "current_page", "last_page", "counts" ], "properties": { "total": { "description": "The withholdings every filter matches, `status` included.", "type": "integer", "example": 1, "minimum": 0 }, "per_page": { "type": "integer", "example": 50, "maximum": 100, "minimum": 1 }, "current_page": { "type": "integer", "example": 1, "minimum": 1 }, "last_page": { "description": "At least 1, even when nothing matches.", "type": "integer", "example": 1, "minimum": 1 }, "counts": { "description": "The withholdings of each status under every filter but `status`; the known statuses are always named, at zero when empty, and a status a later slice adds is listed too.", "required": [ "determined", "certified", "remitted", "voided" ], "properties": { "determined": { "type": "integer", "example": 0, "minimum": 0 }, "certified": { "type": "integer", "example": 1, "minimum": 0 }, "remitted": { "type": "integer", "example": 0, "minimum": 0 }, "voided": { "type": "integer", "example": 0, "minimum": 0 } }, "type": "object", "additionalProperties": { "type": "integer" } } }, "type": "object", "additionalProperties": false }, "FiscalVatWithholdingVoidResult": { "description": "A VAT withholding once voided (MER-3110): its status and why, when and by whom.", "required": [ "id", "status", "voiding" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "0199d1a0-0000-7000-8000-000000000001" }, "status": { "type": "string", "enum": [ "voided" ] }, "voiding": { "required": [ "voided_at", "reason", "voided_by_user_id" ], "properties": { "voided_at": { "description": "ISO 8601 in UTC.", "type": "string", "format": "date-time", "example": "2026-10-08T14:30:00+00:00" }, "reason": { "type": "string", "example": "Monto mal calculado; se reemitirá.", "maxLength": 500 }, "voided_by_user_id": { "description": "Who voided it; null outside a user's request.", "type": "string", "example": "42", "nullable": true } }, "type": "object", "additionalProperties": false } }, "type": "object", "additionalProperties": false }, "VatWorkpaperDocumentsFilter": { "description": "Declared-document filter a VAT workpaper figure drills into: one book and the document types that feed that bucket (MER-4147).", "required": [ "book", "types" ], "properties": { "book": { "type": "string", "example": "sales", "enum": [ "sales", "purchases" ] }, "types": { "type": "array", "items": { "type": "string", "enum": [ "invoice", "credit_note", "debit_note", "received_vat_withholding", "practiced_vat_withholding" ] }, "example": [ "invoice", "credit_note", "debit_note" ], "minItems": 1 } }, "type": "object" }, "FiscalWithholdingCertificate": { "required": [ "id", "series", "number", "period", "issued_on", "fortnight", "status", "validation_locked", "agent", "provider", "withholdings", "delivery" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "0199c3a0-1111-7abc-9def-000000000001" }, "series": { "description": "The company's Certificate Series that numbered it: one per kind of withholding, each counting on its own. Its withholdings are all of that kind.", "type": "string", "enum": [ "vat_withholding", "islr_withholding" ] }, "number": { "description": "AAAAMM of the issuance month and the series' eight-digit counter, which continues across months (PA 2025/000054 art. 16).", "type": "string", "pattern": "^\\d{4}(0[1-9]|1[0-2])\\d{8}$", "example": "20260900000001" }, "period": { "description": "The issuance month: the number's first six digits.", "type": "string", "pattern": "^\\d{4}(0[1-9]|1[0-2])$", "example": "202609" }, "legal_basis": { "description": "Legal legend selected by the original issuance day, never the reprint date.", "type": "string" }, "issued_on": { "description": "The company's day it was issued on, in its time zone.", "type": "string", "format": "date", "example": "2026-09-24" }, "fortnight": { "description": "The fortnight of the withholdings it certifies, from their trigger date: a VAT withholding is declared in it, an ISLR withholding in its month (YYYY-MM).", "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])-[12]$", "example": "2026-09-1" }, "status": { "type": "string", "enum": [ "issued", "voided" ] }, "validation_locked": { "description": "true while the company's withholding certificates are not validated (Withholding Certificate Validation pending the accountant's ruling, MER-2751): the certificate prints «NO VALIDADO» and a new delivery answers 422 withholding_certificate_delivery_locked. Read from the company on every request, never stored on the certificate; the same for issued and voided certificates of either series.", "type": "boolean", "example": true }, "agent": { "description": "The company as withholding agent, as its Fiscal Profile stood on issuance.", "required": [ "rif", "legal_name", "fiscal_address" ], "properties": { "rif": { "type": "string", "example": "J-00000000-0" }, "legal_name": { "type": "string", "example": "QA Fiscal Company, C.A.", "maxLength": 255 }, "fiscal_address": { "type": "string", "example": "Av. Principal, Torre QA, Caracas", "maxLength": 500 } }, "type": "object", "additionalProperties": false }, "provider": { "description": "The provider as the purchase's approval froze its fiscal identity.", "required": [ "id", "document_type", "document_number", "legal_name", "vat_taxpayer_type", "special_taxpayer_since", "islr_person_type" ], "properties": { "fiscal_address": { "description": "Frozen at certificate issuance; null for historical certificates.", "type": "string", "nullable": true, "maxLength": 500 }, "email": { "description": "Frozen at certificate issuance; null for historical certificates.", "type": "string", "nullable": true, "maxLength": 254 }, "id": { "type": "string", "format": "uuid" }, "document_type": { "type": "string", "enum": [ "rif", "cedula", "passport" ] }, "document_number": { "type": "string", "example": "J-00123072-6" }, "legal_name": { "type": "string", "example": "Proveedor Fiscal QA C.A.", "maxLength": 255 }, "vat_taxpayer_type": { "type": "string", "nullable": true, "enum": [ "ordinary", "formal", "non_taxpayer" ] }, "special_taxpayer_since": { "type": "string", "format": "date", "nullable": true }, "islr_person_type": { "type": "string", "nullable": true, "enum": [ "natural_resident", "natural_non_resident", "legal_domiciled", "legal_non_domiciled" ] } }, "type": "object", "additionalProperties": false }, "withholdings": { "description": "The withholdings it certifies, in print order: VAT withholdings on a vat_withholding certificate, ISLR withholdings on an islr_withholding one.", "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/FiscalCertifiedWithholding" }, { "$ref": "#/components/schemas/FiscalCertifiedIslrWithholding" } ] }, "minItems": 1 }, "delivery": { "description": "When and how it reached the provider; null until recorded.", "required": [ "delivered_at", "channel", "delivered_by_user_id" ], "properties": { "delivered_at": { "description": "ISO 8601 in UTC.", "type": "string", "format": "date-time", "example": "2026-10-01T14:30:00+00:00" }, "channel": { "type": "string", "enum": [ "email", "whatsapp", "in_person", "provider_portal" ] }, "delivered_by_user_id": { "description": "The user who first recorded it; null when an API key did.", "type": "string", "example": "42", "nullable": true } }, "type": "object", "nullable": true, "additionalProperties": false } }, "type": "object", "additionalProperties": false }, "FiscalCertifiedWithholding": { "description": "A VAT withholding a vat_withholding certificate certifies.", "required": [ "withholding_id", "purchases_invoice_id", "invoice_number", "control_number", "invoice_date", "taxable_base_ves", "vat_ves", "percentage", "withheld_amount_ves" ], "properties": { "withholding_id": { "type": "string", "format": "uuid" }, "purchases_invoice_id": { "type": "string", "format": "uuid" }, "invoice_number": { "description": "The supplier's invoice number.", "type": "string", "example": "FAC-0199C3", "maxLength": 30 }, "control_number": { "description": "The supplier's control number; null when its document type carries none.", "type": "string", "example": "00-0199C3A0", "nullable": true, "maxLength": 30 }, "invoice_total_ves": { "description": "Invoice or debit-note total frozen on issuance, in bolivares. Null on historical certificates; never backfilled.", "type": "string", "pattern": "^\\d+\\.\\d{2}$", "nullable": true }, "invoice_date": { "description": "The day the supplier issued the invoice.", "type": "string", "format": "date", "example": "2026-09-09" }, "taxable_base_ves": { "description": "The invoice's taxable base over its VAT groups, in bolívars.", "type": "string", "pattern": "^\\d+\\.\\d{2}$", "example": "13000.00" }, "vat_ves": { "description": "The VAT charged in bolívars that the withholding applied its percentage to.", "type": "string", "pattern": "^\\d+\\.\\d{2}$", "example": "2080.00" }, "percentage": { "type": "string", "pattern": "^\\d{1,3}\\.\\d{2}$", "example": "75.00" }, "withheld_amount_ves": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "example": "1560.00" } }, "type": "object", "additionalProperties": false }, "FiscalCertifiedIslrWithholding": { "description": "An ISLR withholding an islr_withholding certificate certifies (MER-3701): the invoice, the amount withheld and the concepts it withheld under. The invoice's VAT taxable base is not printed.", "required": [ "withholding_id", "purchases_invoice_id", "invoice_number", "control_number", "invoice_date", "withheld_amount_ves", "concepts" ], "properties": { "withholding_id": { "type": "string", "format": "uuid" }, "purchases_invoice_id": { "type": "string", "format": "uuid" }, "invoice_number": { "description": "The supplier's invoice number.", "type": "string", "example": "FAC-0199C3", "maxLength": 30 }, "control_number": { "description": "The supplier's control number; null when its document type carries none.", "type": "string", "example": "00-0199C3A0", "nullable": true, "maxLength": 30 }, "invoice_total_ves": { "description": "Invoice or debit-note total frozen on issuance, in bolivares. Null on historical certificates; never backfilled.", "type": "string", "pattern": "^\\d+\\.\\d{2}$", "nullable": true }, "invoice_date": { "description": "The day the supplier issued the invoice.", "type": "string", "format": "date", "example": "2026-09-09" }, "withheld_amount_ves": { "description": "The ISLR withheld in bolívars: the sum of its concepts, more than zero.", "type": "string", "pattern": "^\\d+\\.\\d{2}$", "example": "192.50" }, "concepts": { "description": "The concepts it withheld under, in the withholding's order; a concept that withholds nothing is not printed.", "type": "array", "items": { "$ref": "#/components/schemas/FiscalCertifiedIslrConcept" }, "minItems": 1 } }, "type": "object", "additionalProperties": false }, "FiscalCertifiedIslrConcept": { "required": [ "code", "label", "base_ves", "subject_base_ves", "percentage", "subtractor_ves", "withheld_amount_ves" ], "properties": { "code": { "description": "The ISLR concept's code in the catalog (Decree 1.808 art. 9).", "type": "string", "pattern": "^[a-z][a-z0-9_]{0,63}$", "example": "professional_fees" }, "label": { "description": "The concept's label as the catalog named it on issuance.", "type": "string", "example": "Honorarios profesionales no mercantiles", "maxLength": 120, "minLength": 1 }, "base_ves": { "description": "What was paid for the concept, in bolívars.", "type": "string", "pattern": "^\\d+\\.\\d{2}$", "example": "10000.00" }, "subject_base_ves": { "description": "The share of the base the rate applies to, in bolívars.", "type": "string", "pattern": "^\\d+\\.\\d{2}$", "example": "10000.00" }, "percentage": { "description": "The withholding rate.", "type": "string", "pattern": "^\\d{1,3}\\.\\d{2}$", "example": "3.00" }, "subtractor_ves": { "description": "The subtractor, rounded once for print; null when the concept has none.", "type": "string", "pattern": "^\\d+\\.\\d{2}$", "example": "107.50", "nullable": true }, "withheld_amount_ves": { "description": "The ISLR withheld under the concept, in bolívars; more than zero.", "type": "string", "pattern": "^\\d+\\.\\d{2}$", "example": "192.50" } }, "type": "object", "additionalProperties": false }, "FiscalWithholdingRemittance": { "description": "A Withholding Remittance (MER-3111, MER-3690, MER-3703, ADR 0196): the payment to SENIAT of the VAT or ISLR withholdings the company practised, or of the IGTF it perceived on collection method lines, in one period of its kind (a fortnight for VAT and IGTF, a month for ISLR), through one payment instrument, with the bank reference that reconciles it. What it pays is `remitted` while it stands; voiding it returns the withholdings to `certified` and the lines to `pending_remittance`.", "required": [ "id", "kind", "period", "remitted_on", "bank_reference", "payment_instrument_id", "treasury_account_id", "amount", "status", "voidable", "withholdings", "collection_method_lines", "recorded_at", "recorded_by_user_id", "voiding" ], "properties": { "id": { "description": "The id the client generated (UUIDv7), which makes recording idempotent.", "type": "string", "format": "uuid", "example": "0199e0a0-0000-7000-8000-000000000025" }, "kind": { "description": "What it pays: VAT withholdings (`withholdings`), the IGTF perceived on collection method lines (`collection_method_lines`) or ISLR withholdings (`withholdings`); treat a kind you do not know as another withholding tax.", "type": "string", "enum": [ "vat_withholding", "igtf_perceived", "islr_withholding" ] }, "period": { "description": "The period of every withholding or line it pays, by kind: the fortnight `YYYY-MM-1` / `YYYY-MM-2` for `vat_withholding` and `igtf_perceived`, the month `YYYY-MM` for `islr_withholding`.", "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])(-[12])?$", "example": "2026-09-1" }, "remitted_on": { "description": "The day it was paid to SENIAT.", "type": "string", "format": "date", "example": "2026-09-24" }, "bank_reference": { "type": "string", "example": "SIM-Q1-IVA-25", "maxLength": 120 }, "payment_instrument_id": { "type": "string", "format": "uuid", "example": "0199e0a0-0000-7000-8000-0000000000b1" }, "treasury_account_id": { "description": "The Treasury Account the instrument was linked to when it was recorded (ADR 0183).", "type": "string", "format": "uuid", "example": "0199e0a0-0000-7000-8000-0000000000c1" }, "amount": { "description": "The bolívars paid: the sum of what it paid of each withholding or line.", "required": [ "amount", "currency" ], "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "example": "2760.00" }, "currency": { "type": "string", "enum": [ "VES" ] } }, "type": "object", "additionalProperties": false }, "status": { "type": "string", "enum": [ "recorded", "voided" ] }, "voidable": { "description": "Whether it may be voided now, the rule the server applies: true while `recorded`.", "type": "boolean" }, "withholdings": { "description": "What it paid of each withholding, in ascending withholding id order; empty unless `kind` is `vat_withholding` or `islr_withholding`.", "type": "array", "items": { "required": [ "withholding_id", "amount_ves" ], "properties": { "withholding_id": { "type": "string", "format": "uuid", "example": "0199d1a0-0000-7000-8000-000000000008" }, "amount_ves": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "example": "1200.00" } }, "type": "object", "additionalProperties": false } }, "collection_method_lines": { "description": "What it paid of each collection method line's perceived IGTF, in ascending line id order; empty unless `kind` is `igtf_perceived` (MER-3690).", "type": "array", "items": { "required": [ "collection_method_line_id", "amount_ves" ], "properties": { "collection_method_line_id": { "type": "string", "format": "uuid", "example": "0199e0a0-0000-7000-8000-0000000014a1" }, "amount_ves": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "example": "208.80" } }, "type": "object", "additionalProperties": false } }, "recorded_at": { "description": "ISO 8601 in UTC.", "type": "string", "format": "date-time", "example": "2026-09-25T20:00:00+00:00" }, "recorded_by_user_id": { "description": "Who recorded it; null outside a user's request.", "type": "string", "example": "42", "nullable": true }, "voiding": { "description": "Why, when and by whom it was voided; null while it stands.", "required": [ "voided_at", "reason", "voided_by_user_id" ], "properties": { "voided_at": { "description": "ISO 8601 in UTC.", "type": "string", "format": "date-time", "example": "2026-10-08T14:30:00+00:00" }, "reason": { "type": "string", "example": "Referencia bancaria equivocada; se registrará de nuevo.", "maxLength": 500 }, "voided_by_user_id": { "type": "string", "example": "42", "nullable": true } }, "type": "object", "nullable": true, "additionalProperties": false } }, "type": "object", "additionalProperties": false }, "WithholdingWorkpaperListFilter": { "description": "Status + period filter the existing list uses to show one workpaper bucket (MER-4148). VAT and IGTF carry `fortnight`; ISLR carries `month`.", "required": [ "status" ], "properties": { "status": { "type": "string", "example": "certified" }, "fortnight": { "description": "Present for vat_withholding and igtf_perceived", "type": "string", "example": "2026-09-1" }, "month": { "description": "Present for islr_withholding", "type": "string", "example": "2026-09" } }, "type": "object" }, "WithholdingWorkpaperBucket": { "required": [ "amount", "count", "filter" ], "properties": { "amount": { "type": "string", "example": "1200.00" }, "count": { "type": "integer", "example": 1 }, "filter": { "$ref": "#/components/schemas/WithholdingWorkpaperListFilter" } }, "type": "object" }, "WithholdingWorkpaperRemittance": { "required": [ "id", "remitted_on", "payment_instrument_id", "amount" ], "properties": { "id": { "type": "string", "format": "uuid" }, "remitted_on": { "type": "string", "format": "date", "example": "2026-09-24" }, "payment_instrument_id": { "type": "string", "format": "uuid" }, "amount": { "type": "string", "example": "2760.00" } }, "type": "object" }, "WithholdingWorkpaperRemittedBucket": { "required": [ "amount", "count", "filter", "remittances" ], "properties": { "amount": { "type": "string", "example": "2760.00" }, "count": { "type": "integer", "example": 2 }, "filter": { "$ref": "#/components/schemas/WithholdingWorkpaperListFilter" }, "remittances": { "type": "array", "items": { "$ref": "#/components/schemas/WithholdingWorkpaperRemittance" } } }, "type": "object" }, "WithholdingWorkpaperProblem": { "description": "A refusal of the withholding-workpapers endpoint (MER-4148).", "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string" }, "error_code": { "type": "string", "example": "remittance_period_type_mismatch", "nullable": true }, "errors": { "type": "object", "nullable": true }, "expected_period_type": { "type": "string", "example": "month", "enum": [ "fortnight", "month" ] } }, "type": "object" }, "ImportTemplateProblem": { "description": "Answered by route can: middleware (403 Forbidden without the view permission) or by the controller (a reported 500 on an unexpected failure).", "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string", "example": "Forbidden" }, "status": { "type": "integer", "example": 403 }, "detail": { "type": "string", "example": "You do not have permission to access this resource." }, "error_code": { "type": "string", "nullable": true }, "errors": { "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" }, "ImportTemplateMiddlewareForbidden": { "description": "Answered before the controller runs by the tenant middleware stack: API-key guardrails, company access for a caller outside the company, or tenant membership.", "required": [ "title", "status", "detail" ], "properties": { "title": { "type": "string", "example": "Forbidden" }, "status": { "type": "integer", "example": 403 }, "detail": { "type": "string", "example": "You do not have access to this company" }, "reason": { "description": "Present only when tenant membership is denied; absent from the API-key and company access denials.", "type": "string" } }, "type": "object" }, "AdjustmentLabel": { "required": [ "id", "name", "tone", "archived" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "tone": { "type": "string" }, "archived": { "description": "An archived label stays visible on the documents that carry it", "type": "boolean" } }, "type": "object" }, "AdjustmentLine": { "description": "Quantity and unit are in the item's base unit. Every decimal is an exact string; the valuation fields are null until the adjustment is approved.", "required": [ "id", "categoryId", "itemId", "quantity", "unitId", "unitPrice", "subTotal", "offsetAccountId", "assetAccountId", "reportingUnitPrice", "functionalUnitCost", "reportingUnitCost", "functionalCurrency", "functionalAmount", "reportingCurrency", "reportingAmount" ], "properties": { "id": { "type": "string", "format": "uuid" }, "categoryId": { "type": "string", "format": "uuid" }, "itemId": { "type": "string", "format": "uuid" }, "quantity": { "type": "string", "pattern": "^\\d{1,11}(\\.\\d{1,4})?$", "example": "1.5000" }, "unitId": { "type": "string", "format": "uuid" }, "unitPrice": { "description": "Stored with 2 decimals", "type": "string", "pattern": "^\\d{1,13}(\\.\\d{1,8})?$", "example": "25.50" }, "subTotal": { "description": "As entered; positive lines post this value on approval", "type": "string", "pattern": "^\\d{1,13}(\\.\\d{1,2})?$", "example": "38.25" }, "offsetAccountId": { "type": "string", "format": "uuid" }, "assetAccountId": { "type": "string", "format": "uuid" }, "reportingUnitPrice": { "description": "Reporting-book unit price typed on a positive line, if any.", "type": "string", "example": "0.80000000", "nullable": true }, "functionalUnitCost": { "description": "Functional-book cost per base unit frozen on approval; null until approved.", "type": "string", "example": "100.00000000", "nullable": true }, "reportingUnitCost": { "description": "Reporting-book cost per base unit frozen on approval; null until approved.", "type": "string", "example": "0.80000000", "nullable": true }, "functionalCurrency": { "description": "Currency of the functional book value; null until approved.", "type": "string", "example": "VES", "nullable": true }, "functionalAmount": { "description": "Value the approval posted in the functional book; null until approved.", "type": "string", "example": "1000.00", "nullable": true }, "reportingCurrency": { "description": "Currency of the reporting book value; null until approved.", "type": "string", "example": "USD", "nullable": true }, "reportingAmount": { "description": "Value the approval posted in the reporting book; null until approved.", "type": "string", "example": "8.00", "nullable": true } }, "type": "object" }, "AdjustmentResource": { "description": "A list row and the record share this shape.", "required": [ "id", "code", "type", "reason", "status", "locationId", "locationName", "accountingCenterId", "companyId", "responsibleUserId", "responsibleUserName", "total", "createdAt", "updatedAt", "labels", "items" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string", "example": "AJS2600012" }, "type": { "type": "string", "enum": [ "positive", "negative" ] }, "reason": { "type": "string", "example": "Donación recibida" }, "status": { "description": "Only pending takes edits and a new Responsable", "type": "string", "enum": [ "pending", "approved", "rejected" ] }, "locationId": { "type": "string", "format": "uuid" }, "locationName": { "description": "Null when the location is no longer available", "type": "string", "nullable": true }, "accountingCenterId": { "type": "string", "format": "uuid" }, "companyId": { "type": "string", "format": "uuid" }, "responsibleUserId": { "description": "Optional Responsable as a string; null when none. It changes only through PUT /{id}/responsible", "type": "string", "example": "42", "nullable": true }, "responsibleUserName": { "description": "Null when there is no Responsable or the user is no longer available", "type": "string", "nullable": true }, "total": { "description": "Sum of the lines' subTotal as entered; the value an approval posted is each line's functionalAmount", "type": "string", "pattern": "^\\d+\\.\\d{2}$", "example": "38.25" }, "createdAt": { "type": "string", "format": "date-time", "example": "2026-10-13T14:00:00+00:00", "nullable": true }, "updatedAt": { "type": "string", "format": "date-time", "example": "2026-10-13T15:10:00+00:00", "nullable": true }, "labels": { "type": "array", "items": { "$ref": "#/components/schemas/AdjustmentLabel" } }, "items": { "description": "In ascending line id", "type": "array", "items": { "$ref": "#/components/schemas/AdjustmentLine" } } }, "type": "object" }, "AdjustmentsPage": { "required": [ "data", "total", "per_page", "current_page", "currentPage", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AdjustmentResource" } }, "total": { "description": "Rows that match every filter", "type": "integer", "minimum": 0 }, "per_page": { "type": "integer", "maximum": 100, "minimum": 1 }, "current_page": { "type": "integer", "minimum": 1 }, "currentPage": { "description": "Same as current_page", "type": "integer", "deprecated": true, "minimum": 1 }, "meta": { "required": [ "counts", "label_counts" ], "properties": { "counts": { "description": "Rows per status under every filter except status", "required": [ "pending", "approved", "rejected" ], "properties": { "pending": { "type": "integer", "minimum": 0 }, "approved": { "type": "integer", "minimum": 0 }, "rejected": { "type": "integer", "minimum": 0 } }, "type": "object" }, "label_counts": { "description": "Distinct rows per active label under every filter except label_ids; {} when none", "type": "object", "additionalProperties": { "type": "integer", "minimum": 0 } } }, "type": "object" } }, "type": "object" }, "AdjustmentCreated": { "required": [ "id" ], "properties": { "id": { "description": "The id the request sent; navigate with it and read the code from the record", "type": "string", "format": "uuid" } }, "type": "object" }, "AdjustmentResponsibleRequest": { "required": [ "responsibleUserId" ], "properties": { "responsibleUserId": { "description": "Canonical id of a user of the adjustment's company, as a string; null clears", "type": "string", "pattern": "^(?:[1-9][0-9]{0,17}|[1-8][0-9]{18}|9[0-1][0-9]{17}|92[0-1][0-9]{16}|922[0-2][0-9]{15}|9223[0-2][0-9]{14}|92233[0-6][0-9]{13}|922337[0-1][0-9]{12}|92233720[0-2][0-9]{10}|922337203[0-5][0-9]{9}|9223372036[0-7][0-9]{8}|92233720368[0-4][0-9]{7}|922337203685[0-3][0-9]{6}|9223372036854[0-6][0-9]{5}|92233720368547[0-6][0-9]{4}|922337203685477[0-4][0-9]{3}|9223372036854775[0-7][0-9]{2}|922337203685477580[0-6]|9223372036854775807)$", "nullable": true } }, "type": "object" }, "AdjustmentAcknowledgement": { "description": "Empty JSON object acknowledgement", "type": "object" }, "AdjustmentProblem": { "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "error_code": { "type": "string", "nullable": true }, "errors": { "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" }, "AdjustmentClosedProblem": { "description": "adjustment_cannot_be_modified: the adjustment is approved or rejected and takes no edit", "required": [ "title", "status", "detail", "error_code", "errors", "adjustment_status" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "error_code": { "type": "string", "enum": [ "adjustment_cannot_be_modified" ] }, "errors": { "type": "object", "nullable": true }, "adjustment_status": { "type": "string", "enum": [ "approved", "rejected" ] } }, "type": "object" }, "AdjustmentUnauthenticated": { "required": [ "message" ], "properties": { "message": { "type": "string" } }, "type": "object" }, "AdjustmentForbidden": { "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "error_code": { "type": "string", "nullable": true }, "errors": { "type": "object", "nullable": true } }, "type": "object" }, "CounterCatalogItem": { "description": "An active Item as the sale station shows it: exactly these ten fields, never a price, a cost or a stock.", "required": [ "id", "code", "sku", "barcode", "name", "category_id", "base_unit_id", "variant_group", "variant_options", "thumbnail_url" ], "properties": { "id": { "description": "The counter catalog read components (MER-5156, ADR 0321): exactly the\nfields the POS reads, as closed objects, never a price, a cost or a stock.", "type": "string", "format": "uuid" }, "code": { "type": "string", "example": "ITM2600001" }, "sku": { "description": "«SKU», stored as written; null when the Item has none.", "type": "string", "nullable": true }, "barcode": { "description": "«Código de barras», stored as written; null when the Item has none.", "type": "string", "example": "7591234567890", "nullable": true }, "name": { "type": "string", "example": "Guantes de nitrilo" }, "category_id": { "description": "The Item's category; null only for an Item gone between two reads.", "type": "string", "format": "uuid", "nullable": true }, "base_unit_id": { "description": "The Item's base unit; null only for an Item without one.", "type": "string", "format": "uuid", "nullable": true }, "variant_group": { "description": "The Modelo the Item is a Variante of; null outside any Modelo.", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "example": "Polo" } }, "type": "object", "nullable": true }, "variant_options": { "description": "Its value for each option of its Modelo, in the Modelo's order; null exactly when variant_group is null.", "type": "array", "items": { "$ref": "#/components/schemas/ItemVariantOption" }, "nullable": true }, "thumbnail_url": { "description": "The thumbnail of the Item's primary image; null without one or while it is still processing.", "type": "string", "nullable": true } }, "type": "object", "additionalProperties": false }, "CounterCatalogGroup": { "description": "An active Modelo with its Variantes in code order.", "required": [ "id", "name", "option_names", "variants" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "example": "Polo" }, "option_names": { "description": "The Modelo's option names in its order, the picker's column headers.", "type": "array", "items": { "type": "string", "example": "Talla" } }, "variants": { "description": "Every active Variante on a search answer, possibly none; when browsing, only the active Variantes of category_id, never none.", "type": "array", "items": { "$ref": "#/components/schemas/CounterCatalogItem" } } }, "type": "object", "additionalProperties": false }, "CounterCatalogItemPage": { "required": [ "match", "items", "groups", "current_page", "per_page", "has_more_items", "has_more_groups" ], "properties": { "match": { "description": "barcode, sku or code: one active Item whose identifier equals q exactly, tried in that order. text: names containing q. none: nothing on page 1 of the text phase, and always whenever q is absent.", "type": "string", "enum": [ "barcode", "sku", "code", "text", "none" ] }, "items": { "description": "Searching, prefix matches first, then by name; browsing, by name. A Variante of a listed active Modelo appears only inside its group.", "type": "array", "items": { "$ref": "#/components/schemas/CounterCatalogItem" } }, "groups": { "description": "Active Modelos: searching, those whose name matched, prefix matches first, then by name, always empty for an exact match; browsing, those with an active Variante of category_id, by name.", "type": "array", "items": { "$ref": "#/components/schemas/CounterCatalogGroup" } }, "current_page": { "description": "Always 1 for an exact match.", "type": "integer", "minimum": 1 }, "per_page": { "type": "integer", "maximum": 48, "minimum": 1 }, "has_more_items": { "type": "boolean" }, "has_more_groups": { "type": "boolean" } }, "type": "object", "additionalProperties": false }, "CounterCatalogCategory": { "description": "An active category of the company, for the sale station's grid.", "required": [ "id", "name" ], "properties": { "id": { "description": "The category's id, which pos/catalog/items takes as category_id.", "type": "string", "format": "uuid" }, "name": { "type": "string", "example": "Camisas" } }, "type": "object", "additionalProperties": false }, "CounterCatalogCategoryList": { "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CounterCatalogCategory" } } }, "type": "object" }, "CounterCatalogProblem": { "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "error_code": { "type": "string", "nullable": true }, "errors": { "description": "Request validation messages by field.", "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" }, "InventoryDispatchItem": { "required": [ "id", "inventory_dispatch_id", "item_id", "category_id", "expected_quantity", "quantity_dispatched", "unit_id", "location_id", "company_id", "origin_type", "origin_id", "functional_currency", "functional_cost", "reporting_currency", "reporting_cost" ], "properties": { "id": { "type": "string", "format": "uuid" }, "inventory_dispatch_id": { "type": "string", "format": "uuid" }, "item_id": { "type": "string", "format": "uuid" }, "category_id": { "type": "string", "format": "uuid" }, "unit_id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "expected_quantity": { "description": "Exact nonnegative DECIMAL(15,4) string; maximum 99999999999.9999", "type": "string", "pattern": "^[0-9]{1,11}(\\.[0-9]{1,4})?$", "example": "3.2500" }, "quantity_dispatched": { "description": "Exact nonnegative DECIMAL(15,4) string; maximum 99999999999.9999", "type": "string", "pattern": "^[0-9]{1,11}(\\.[0-9]{1,4})?$", "example": "3.2500" }, "location_id": { "type": "string", "nullable": true }, "origin_id": { "type": "string", "nullable": true }, "origin_type": { "type": "string", "nullable": true }, "functional_currency": { "type": "string", "nullable": true }, "functional_cost": { "type": "string", "nullable": true }, "reporting_currency": { "type": "string", "nullable": true }, "reporting_cost": { "type": "string", "nullable": true } }, "type": "object" }, "InventoryDispatchEnhancedItem": { "required": [ "id", "inventory_dispatch_id", "item_id", "category_id", "expected_quantity", "quantity_dispatched", "unit_id", "location_id", "company_id", "origin_type", "origin_id", "item_name", "category_name", "unit_name", "location_name", "quantity_total", "status" ], "properties": { "id": { "type": "string", "format": "uuid" }, "inventory_dispatch_id": { "type": "string", "format": "uuid" }, "item_id": { "type": "string", "format": "uuid" }, "category_id": { "type": "string", "format": "uuid" }, "unit_id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "expected_quantity": { "description": "Exact nonnegative DECIMAL(15,4) string; maximum 99999999999.9999", "type": "string", "pattern": "^[0-9]{1,11}(\\.[0-9]{1,4})?$", "example": "3.2500" }, "quantity_dispatched": { "description": "Exact nonnegative DECIMAL(15,4) string; maximum 99999999999.9999", "type": "string", "pattern": "^[0-9]{1,11}(\\.[0-9]{1,4})?$", "example": "3.2500" }, "location_id": { "type": "string", "nullable": true }, "origin_id": { "type": "string", "nullable": true }, "origin_type": { "type": "string", "nullable": true }, "item_name": { "type": "string" }, "category_name": { "type": "string" }, "unit_name": { "type": "string" }, "location_name": { "type": "string", "nullable": true }, "quantity_total": { "description": "Exact nonnegative DECIMAL(15,4) string; maximum 99999999999.9999", "type": "string", "pattern": "^[0-9]{1,11}(\\.[0-9]{1,4})?$", "example": "3.2500" }, "status": { "type": "string", "enum": [ "pending", "partial", "completed" ] } }, "type": "object" }, "InventoryDispatchListRow": { "required": [ "id", "code", "date", "origin_type", "origin_type_value", "origin_id", "status", "items_count", "labels", "responsible_user_id", "responsible_user_name" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "date": { "type": "string", "format": "date" }, "origin_id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "origin_type": { "type": "string" }, "origin_type_value": { "type": "string", "enum": [ "sales_order", "sales_invoice", "inventory_transfer" ] }, "origin_reference": { "type": "string" }, "status": { "description": "A status set by hand (cancelled, closed_short) goes ahead of the one calculated from the lines; a dispatch closed short keeps the status of each line.", "type": "string", "enum": [ "pending", "partial", "completed", "cancelled", "closed_short" ] }, "status_display": { "type": "string" }, "hasAccountingConfigurationGaps": { "type": "boolean" }, "carrier": { "type": "string", "nullable": true }, "tracking_number": { "type": "string", "nullable": true }, "prepared_at": { "type": "string", "nullable": true }, "shipped_at": { "type": "string", "nullable": true }, "delivered_at": { "type": "string", "nullable": true }, "received_by": { "type": "string", "nullable": true }, "origin_code": { "type": "string", "nullable": true }, "customer_name": { "type": "string", "nullable": true }, "responsible_user_id": { "type": "string", "nullable": true }, "responsible_user_name": { "type": "string", "nullable": true }, "items_count": { "type": "integer", "minimum": 0 }, "created_at": { "type": "string", "format": "date-time", "nullable": true }, "updated_at": { "type": "string", "format": "date-time", "nullable": true }, "labels": { "type": "array", "items": { "required": [ "id", "name", "tone", "archived" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "tone": { "type": "string" }, "archived": { "type": "boolean" } }, "type": "object" } } }, "type": "object" }, "InventoryDispatchEnhancedResource": { "required": [ "id", "code", "date", "origin_type", "origin_id", "status", "items", "items_count", "labels", "responsible_user_id", "responsible_user_name", "sold_at_the_counter", "has_returned_units" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "date": { "type": "string", "format": "date" }, "origin_id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "origin_type": { "type": "string", "enum": [ "sales_order", "sales_invoice", "inventory_transfer" ] }, "origin_reference": { "type": "string" }, "sold_at_the_counter": { "description": "Whether its Sales Invoice is a Venta de mostrador's, charged or voided (MER-4978). Such a dispatch goes back to Pending only by voiding the sale at the till, so POST inventory/dispatches/{id}/revert refuses it with 409. False for a Sales Order's, a Backoffice invoice's or a transfer's dispatch.", "type": "boolean" }, "has_returned_units": { "description": "Whether a live approved Unit Return credits units of its sale (MER-2942). A sales dispatch does not go back to Pending while one does, so POST inventory/dispatches/{id}/revert answers 409 inventory_dispatch_cannot_be_reverted.", "type": "boolean" }, "status": { "description": "A status set by hand (cancelled, closed_short) goes ahead of the one calculated from the lines; a dispatch closed short keeps the status of each line.", "type": "string", "enum": [ "pending", "partial", "completed", "cancelled", "closed_short" ] }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/InventoryDispatchEnhancedItem" } }, "origin_code": { "type": "string", "nullable": true }, "customer_name": { "type": "string", "nullable": true }, "responsible_user_id": { "type": "string", "nullable": true }, "responsible_user_name": { "type": "string", "nullable": true }, "items_count": { "type": "integer", "minimum": 0 }, "created_at": { "type": "string", "format": "date-time", "nullable": true }, "updated_at": { "type": "string", "format": "date-time", "nullable": true }, "labels": { "type": "array", "items": { "required": [ "id", "name", "tone", "archived" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "tone": { "type": "string" }, "archived": { "type": "boolean" } }, "type": "object" } } }, "type": "object" }, "InventoryDispatchResource": { "required": [ "id", "code", "date", "origin_type", "origin_id", "company_id", "items", "responsible_user_id" ], "properties": { "guide_number": { "type": "string", "nullable": true }, "guide_control": { "type": "string", "nullable": true }, "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "date": { "type": "string", "format": "date" }, "origin_id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "origin_type": { "type": "string", "enum": [ "sales_order", "sales_invoice", "inventory_transfer" ] }, "responsible_user_id": { "type": "string", "nullable": true }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/InventoryDispatchItem" } } }, "type": "object" }, "InventoryDispatchesPage": { "required": [ "dispatches", "total", "perPage", "currentPage", "meta" ], "properties": { "dispatches": { "type": "array", "items": { "$ref": "#/components/schemas/InventoryDispatchListRow" } }, "total": { "type": "integer", "minimum": 0 }, "perPage": { "type": "integer", "maximum": 100, "minimum": 1 }, "currentPage": { "type": "integer", "minimum": 1 }, "meta": { "required": [ "counts", "label_counts", "origin_type_counts", "responsible_user_counts" ], "properties": { "counts": { "required": [ "pending", "partial", "completed", "closed_short", "cancelled" ], "properties": { "pending": { "type": "integer", "minimum": 0 }, "partial": { "type": "integer", "minimum": 0 }, "completed": { "type": "integer", "minimum": 0 }, "closed_short": { "type": "integer", "minimum": 0 }, "cancelled": { "type": "integer", "minimum": 0 } }, "type": "object" }, "origin_type_counts": { "required": [ "sales_order", "sales_invoice", "inventory_transfer" ], "properties": { "sales_order": { "type": "integer", "minimum": 0 }, "sales_invoice": { "type": "integer", "minimum": 0 }, "inventory_transfer": { "type": "integer", "minimum": 0 } }, "type": "object" }, "label_counts": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 0 } }, "responsible_user_counts": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 0 } } }, "type": "object" } }, "type": "object" }, "InventoryDispatchQuantityRequest": { "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "required": [ "inventory_dispatch_item_id", "quantity_dispatched" ], "properties": { "inventory_dispatch_item_id": { "type": "string", "format": "uuid" }, "quantity_dispatched": { "description": "Exact nonnegative DECIMAL(15,4) string; maximum 99999999999.9999", "type": "string", "pattern": "^[0-9]{1,11}(\\.[0-9]{1,4})?$", "example": "3.2500" } }, "type": "object" } } }, "type": "object" }, "InventoryDispatchResponsibleRequest": { "required": [ "responsible_user_id" ], "properties": { "responsible_user_id": { "description": "Canonical company user ID within 1..9223372036854775807; null clears", "type": "string", "pattern": "^(?:[1-9][0-9]{0,17}|[1-8][0-9]{18}|9[0-1][0-9]{17}|92[0-1][0-9]{16}|922[0-2][0-9]{15}|9223[0-2][0-9]{14}|92233[0-6][0-9]{13}|922337[0-1][0-9]{12}|92233720[0-2][0-9]{10}|922337203[0-5][0-9]{9}|9223372036[0-7][0-9]{8}|92233720368[0-4][0-9]{7}|922337203685[0-3][0-9]{6}|9223372036854[0-6][0-9]{5}|92233720368547[0-6][0-9]{4}|922337203685477[0-4][0-9]{3}|9223372036854775[0-7][0-9]{2}|922337203685477580[0-6]|9223372036854775807)$", "nullable": true } }, "type": "object" }, "InventoryDispatchProblem": { "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "error_code": { "type": "string", "nullable": true }, "errors": { "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" }, "InventoryDispatchUnauthenticated": { "required": [ "message" ], "properties": { "message": { "type": "string" } }, "type": "object" }, "InventoryDispatchForbidden": { "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "error_code": { "type": "string", "nullable": true }, "errors": { "type": "object", "nullable": true } }, "type": "object" }, "InventoryDispatchAcknowledgement": { "description": "Empty JSON object acknowledgement", "type": "object" }, "InventoryDispatchResponsibleAcknowledgement": { "description": "Empty JSON object acknowledgement", "type": "object" }, "InventoryDispatchDecreaseProblem": { "required": [ "title", "status", "detail", "error_code", "errors", "inventory_dispatch_item_id", "current_quantity_dispatched", "attempted_quantity_dispatched" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "error_code": { "type": "string", "nullable": true }, "errors": { "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "inventory_dispatch_item_id": { "type": "string", "format": "uuid" }, "current_quantity_dispatched": { "description": "Exact nonnegative DECIMAL(15,4) string; maximum 99999999999.9999", "type": "string", "pattern": "^[0-9]{1,11}(\\.[0-9]{1,4})?$", "example": "3.2500" }, "attempted_quantity_dispatched": { "description": "Exact nonnegative DECIMAL(15,4) string; maximum 99999999999.9999", "type": "string", "pattern": "^[0-9]{1,11}(\\.[0-9]{1,4})?$", "example": "3.2500" } }, "type": "object" }, "InventoryDispatchStockProblem": { "required": [ "title", "status", "detail", "error_code", "errors", "insufficient_stock_items" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "error_code": { "type": "string", "nullable": true }, "errors": { "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "insufficient_stock_items": { "type": "object", "additionalProperties": { "required": [ "inventory_dispatch_item_id", "item_id", "location_id", "available_quantity", "required_increase", "attempted_quantity" ], "properties": { "inventory_dispatch_item_id": { "type": "string" }, "item_id": { "type": "string" }, "location_id": { "type": "string" }, "available_quantity": { "type": "string" }, "required_increase": { "type": "string" }, "attempted_quantity": { "type": "string" } }, "type": "object" } } }, "type": "object" }, "InventoryDispatchAccountingConfigurationError": { "required": [ "error", "missing" ], "properties": { "error": { "type": "string", "enum": [ "accounting_configuration_incomplete" ] }, "missing": { "type": "array", "items": { "required": [ "reason_code", "subject_type", "subject_id", "human_message", "details" ], "properties": { "reason_code": { "type": "string" }, "subject_type": { "type": "string" }, "subject_id": { "type": "string" }, "human_message": { "type": "string" }, "details": { "type": "array", "items": { "type": "string" } } }, "type": "object" } } }, "type": "object" }, "InventoryEntryLabel": { "required": [ "id", "name", "tone", "archived" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "tone": { "type": "string" }, "archived": { "description": "An archived label stays visible on the documents that carry it", "type": "boolean" } }, "type": "object" }, "InventoryEntryItem": { "required": [ "id", "inventory_entry_id", "item_id", "category_id", "expected_quantity", "quantity_received", "unit_id", "location_id", "company_id", "origin_type", "origin_id", "document_currency", "functional_rate", "functional_rate_reference", "reporting_rate", "reporting_rate_reference", "rate_rule", "rate_value_date", "rate_known_at", "rate_origin", "functional_unit_cost", "reporting_unit_cost", "received_original_amount", "received_functional_amount", "received_reporting_amount", "returned_functional_currency", "returned_functional_cost", "returned_reporting_currency", "returned_reporting_cost" ], "properties": { "id": { "type": "string", "format": "uuid" }, "inventory_entry_id": { "type": "string", "format": "uuid" }, "item_id": { "type": "string", "format": "uuid" }, "category_id": { "type": "string", "format": "uuid" }, "expected_quantity": { "description": "Exact nonnegative DECIMAL(15,4) string; maximum 99999999999.9999", "type": "string", "pattern": "^[0-9]{1,11}(\\.[0-9]{1,4})?$", "example": "10.0000" }, "quantity_received": { "description": "Exact nonnegative DECIMAL(15,4) string; maximum 99999999999.9999", "type": "string", "pattern": "^[0-9]{1,11}(\\.[0-9]{1,4})?$", "example": "3.2500" }, "unit_id": { "type": "string", "format": "uuid" }, "location_id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "origin_type": { "description": "The document line this entry line comes from; null when it has none", "type": "string", "example": "purchase_order_item", "nullable": true }, "origin_id": { "type": "string", "nullable": true }, "document_currency": { "description": "Currency of the purchase price the line's last valued receipt was priced in; null for a line no valued receipt touched.", "type": "string", "example": "USD", "nullable": true }, "functional_rate": { "description": "Rate of the last receipt's functional leg (ADR 0160).", "type": "string", "example": "120.00000000", "nullable": true }, "functional_rate_reference": { "description": "Official rate row of the functional leg.", "type": "string", "nullable": true }, "reporting_rate": { "description": "Rate of the last receipt's reporting leg.", "type": "string", "example": "120.00000000", "nullable": true }, "reporting_rate_reference": { "description": "Official rate row of the reporting leg.", "type": "string", "nullable": true }, "rate_rule": { "type": "string", "example": "value_date", "nullable": true }, "rate_value_date": { "type": "string", "example": "2026-10-02", "nullable": true }, "rate_known_at": { "type": "string", "example": "2026-10-02T13:00:00+00:00", "nullable": true }, "rate_origin": { "type": "string", "example": "ingested", "nullable": true }, "functional_unit_cost": { "description": "Functional-book cost per base unit of the last receipt.", "type": "string", "example": "1440.00000000", "nullable": true }, "reporting_unit_cost": { "description": "Reporting-book cost per base unit of the last receipt.", "type": "string", "example": "12.00000000", "nullable": true }, "received_original_amount": { "description": "What the line's receipts posted, in the purchase price's currency.", "type": "string", "example": "12.00", "nullable": true }, "received_functional_amount": { "description": "What the line's receipts posted in the functional book; an entry reversal reverses it.", "type": "string", "example": "1440.00", "nullable": true }, "received_reporting_amount": { "description": "What the line's receipts posted in the reporting book; an entry reversal reverses it.", "type": "string", "example": "12.00", "nullable": true }, "returned_functional_currency": { "description": "Currency of returned_functional_cost; null unless this is a Return Entry's line.", "type": "string", "example": "VES", "nullable": true }, "returned_functional_cost": { "description": "What this Return Entry line re-enters at in the functional book, frozen at approval; null on any other line.", "type": "string", "example": "400.00", "nullable": true }, "returned_reporting_currency": { "description": "Currency of returned_reporting_cost; null unless this is a Return Entry's line.", "type": "string", "example": "USD", "nullable": true }, "returned_reporting_cost": { "description": "What this Return Entry line re-enters at in the reporting book, frozen at approval; null on any other line.", "type": "string", "example": "10.00", "nullable": true } }, "type": "object" }, "InventoryEntryEnhancedItem": { "required": [ "id", "inventory_entry_id", "item_id", "category_id", "expected_quantity", "quantity_received", "unit_id", "location_id", "company_id", "origin_type", "origin_id", "item_name", "category_name", "unit_name", "location_name", "status", "returned_functional_currency", "returned_functional_cost", "returned_reporting_currency", "returned_reporting_cost", "quantity_not_received" ], "properties": { "id": { "type": "string", "format": "uuid" }, "inventory_entry_id": { "type": "string", "format": "uuid" }, "item_id": { "type": "string", "format": "uuid" }, "category_id": { "type": "string", "format": "uuid" }, "expected_quantity": { "description": "Exact nonnegative DECIMAL(15,4) string; maximum 99999999999.9999", "type": "string", "pattern": "^[0-9]{1,11}(\\.[0-9]{1,4})?$", "example": "10.0000" }, "quantity_received": { "description": "Exact nonnegative DECIMAL(15,4) string; maximum 99999999999.9999", "type": "string", "pattern": "^[0-9]{1,11}(\\.[0-9]{1,4})?$", "example": "3.2500" }, "unit_id": { "type": "string", "format": "uuid" }, "location_id": { "type": "string", "nullable": true }, "company_id": { "type": "string", "format": "uuid" }, "origin_type": { "type": "string", "nullable": true }, "origin_id": { "type": "string", "nullable": true }, "item_name": { "type": "string" }, "category_name": { "type": "string" }, "unit_name": { "type": "string" }, "location_name": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "pending", "partial", "completed" ] }, "returned_functional_currency": { "description": "Currency of returned_functional_cost; null unless this is a Return Entry's line.", "type": "string", "nullable": true }, "returned_functional_cost": { "description": "What this Return Entry line re-enters at in the functional book, frozen at approval; null on any other line.", "type": "string", "nullable": true }, "returned_reporting_currency": { "description": "Currency of returned_reporting_cost; null unless this is a Return Entry's line.", "type": "string", "nullable": true }, "returned_reporting_cost": { "description": "What this Return Entry line re-enters at in the reporting book, frozen at approval; null on any other line.", "type": "string", "nullable": true }, "quantity_not_received": { "description": "Units this line will not receive: expected_quantity − quantity_received once its Return Entry closed short (R6, ADR 0379), as an exact DECIMAL(15,4) string. Null on any other status: an open entry's units are still to receive, and a cancelled one was undone.", "type": "string", "pattern": "^[0-9]{1,11}(\\.[0-9]{1,4})?$", "example": "2.0000", "nullable": true } }, "type": "object" }, "InventoryEntryListRow": { "required": [ "id", "code", "date", "origin_type", "origin_type_value", "origin_id", "origin_reference", "origin_code", "provider_name", "status", "company_id", "items_count", "responsible_user_id", "responsible_user_name", "labels", "created_at", "updated_at", "hasAccountingConfigurationGaps" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string", "example": "IE2600012" }, "date": { "description": "Receipt instant in RFC 3339, carrying the business zone's offset it was recorded in", "type": "string", "format": "date-time", "example": "2026-10-13T10:00:00-04:00" }, "origin_type": { "description": "Spanish label of origin_type_value, kept for compatibility; read origin_type_value instead", "type": "string", "example": "Traslado de Inventario" }, "origin_type_value": { "type": "string", "enum": [ "purchase_order", "inventory_transfer", "transformation", "sales_credit_note" ] }, "origin_id": { "type": "string", "format": "uuid" }, "origin_reference": { "type": "string", "example": "TR2600003 - Almacén Norte" }, "origin_code": { "description": "Code of the purchase order, transfer, transformation or Sales Credit Note the entry comes from", "type": "string", "nullable": true }, "provider_name": { "description": "Provider of the purchase order; null for other origins", "type": "string", "nullable": true }, "status": { "description": "Calculated from the lines; a cancelled (frozen) entry reads cancelled, and a Return Entry closed short reads closed_short (R6, ADR 0379)", "type": "string", "enum": [ "pending", "partial", "completed", "closed_short", "cancelled" ] }, "company_id": { "type": "string", "format": "uuid" }, "items_count": { "type": "integer", "minimum": 0 }, "responsible_user_id": { "description": "Null means no Responsable", "type": "string", "nullable": true }, "responsible_user_name": { "description": "Null with an id means the user is no longer available in the company", "type": "string", "nullable": true }, "labels": { "type": "array", "items": { "$ref": "#/components/schemas/InventoryEntryLabel" } }, "created_at": { "type": "string", "format": "date-time", "nullable": true }, "updated_at": { "type": "string", "format": "date-time", "nullable": true }, "hasAccountingConfigurationGaps": { "type": "boolean" } }, "type": "object" }, "InventoryEntriesPage": { "required": [ "entries", "total", "perPage", "currentPage", "meta" ], "properties": { "entries": { "type": "array", "items": { "$ref": "#/components/schemas/InventoryEntryListRow" } }, "total": { "type": "integer", "minimum": 0 }, "perPage": { "type": "integer", "maximum": 100, "minimum": 1 }, "currentPage": { "type": "integer", "minimum": 1 }, "meta": { "required": [ "total", "per_page", "current_page", "counts", "origin_type_counts", "responsible_user_counts", "label_counts" ], "properties": { "total": { "description": "Rows that match every filter", "type": "integer", "minimum": 0 }, "per_page": { "type": "integer", "maximum": 100, "minimum": 1 }, "current_page": { "type": "integer", "minimum": 1 }, "counts": { "description": "Rows per status under every filter except status", "required": [ "pending", "partial", "completed", "closed_short", "cancelled" ], "properties": { "pending": { "type": "integer", "minimum": 0 }, "partial": { "type": "integer", "minimum": 0 }, "completed": { "type": "integer", "minimum": 0 }, "closed_short": { "type": "integer", "minimum": 0 }, "cancelled": { "type": "integer", "minimum": 0 } }, "type": "object" }, "origin_type_counts": { "description": "Rows per origin under every filter except origin_type", "required": [ "purchase_order", "inventory_transfer", "transformation", "sales_credit_note" ], "properties": { "purchase_order": { "type": "integer", "minimum": 0 }, "inventory_transfer": { "type": "integer", "minimum": 0 }, "transformation": { "type": "integer", "minimum": 0 }, "sales_credit_note": { "type": "integer", "minimum": 0 } }, "type": "object" }, "responsible_user_counts": { "description": "Rows per assigned Responsable under every filter except responsible_user_id; {} when none", "type": "object", "additionalProperties": { "type": "integer", "minimum": 0 } }, "label_counts": { "description": "Distinct rows per active label under every filter except label_ids; {} when none", "type": "object", "additionalProperties": { "type": "integer", "minimum": 0 } } }, "type": "object" } }, "type": "object" }, "InventoryEntryEnhancedResource": { "required": [ "id", "code", "date", "origin_type", "origin_type_value", "origin_id", "origin_reference", "origin_code", "provider_name", "status", "company_id", "items", "items_count", "responsible_user_id", "responsible_user_name", "labels", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string", "example": "IE2600012" }, "date": { "description": "Receipt instant in RFC 3339, carrying the business zone's offset it was recorded in", "type": "string", "format": "date-time", "example": "2026-10-13T10:00:00-04:00" }, "origin_type": { "description": "Spanish label of origin_type_value, kept for compatibility; read origin_type_value instead", "type": "string", "example": "Traslado de inventario" }, "origin_type_value": { "type": "string", "enum": [ "purchase_order", "inventory_transfer", "transformation", "sales_credit_note" ] }, "origin_id": { "type": "string", "format": "uuid" }, "origin_reference": { "type": "string" }, "origin_code": { "type": "string", "nullable": true }, "provider_name": { "type": "string", "nullable": true }, "status": { "description": "Calculated from the lines; a cancelled (frozen) entry reads cancelled, and a Return Entry closed short reads closed_short (R6, ADR 0379)", "type": "string", "enum": [ "pending", "partial", "completed", "closed_short", "cancelled" ] }, "company_id": { "type": "string", "format": "uuid" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/InventoryEntryEnhancedItem" } }, "items_count": { "type": "integer", "minimum": 0 }, "responsible_user_id": { "type": "string", "nullable": true }, "responsible_user_name": { "type": "string", "nullable": true }, "labels": { "type": "array", "items": { "$ref": "#/components/schemas/InventoryEntryLabel" } }, "created_at": { "type": "string", "format": "date-time", "nullable": true }, "updated_at": { "type": "string", "format": "date-time", "nullable": true } }, "type": "object" }, "InventoryEntryResource": { "required": [ "id", "code", "origin_type", "origin_id", "origin_reference", "date", "company_id", "manual_status", "responsible_user_id", "items" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "origin_type": { "type": "string", "enum": [ "purchase_order", "inventory_transfer", "transformation", "sales_credit_note" ] }, "origin_id": { "type": "string", "format": "uuid" }, "origin_reference": { "description": "The code of its Sales Credit Note, on a Return Entry; null on any other origin.", "type": "string", "nullable": true }, "date": { "description": "Business-zone wall-clock digits as Y-m-d H:i:s, without an offset; read them in the business zone, never as UTC", "type": "string", "example": "2026-10-13 10:00:00" }, "company_id": { "type": "string", "format": "uuid" }, "manual_status": { "description": "cancelled once the entry is frozen, closed_short once a Return Entry closed short (R6, ADR 0379); null otherwise", "type": "string", "nullable": true }, "responsible_user_id": { "type": "string", "nullable": true }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/InventoryEntryItem" } } }, "type": "object" }, "InventoryEntryQuantityRequest": { "description": "Send inventory_entry_item_quantities (or the legacy item_quantities); at least one must hold a quantity", "properties": { "inventory_entry_item_quantities": { "description": "Cumulative quantity received by entry line id", "minProperties": 1, "type": "object", "additionalProperties": { "description": "Exact nonnegative DECIMAL(15,4) string; maximum 99999999999.9999", "type": "string", "pattern": "^[0-9]{1,11}(\\.[0-9]{1,4})?$", "example": "3.2500" } }, "item_quantities": { "description": "Legacy: cumulative quantity received by item id, applied to every line of that item", "minProperties": 1, "type": "object", "deprecated": true, "additionalProperties": { "description": "Exact nonnegative DECIMAL(15,4) string; maximum 99999999999.9999", "type": "string", "pattern": "^[0-9]{1,11}(\\.[0-9]{1,4})?$", "example": "3.2500" } } }, "type": "object" }, "InventoryEntryResponsibleRequest": { "required": [ "responsible_user_id" ], "properties": { "responsible_user_id": { "description": "Canonical company user ID within 1..9223372036854775807; null clears", "type": "string", "pattern": "^(?:[1-9][0-9]{0,17}|[1-8][0-9]{18}|9[0-1][0-9]{17}|92[0-1][0-9]{16}|922[0-2][0-9]{15}|9223[0-2][0-9]{14}|92233[0-6][0-9]{13}|922337[0-1][0-9]{12}|92233720[0-2][0-9]{10}|922337203[0-5][0-9]{9}|9223372036[0-7][0-9]{8}|92233720368[0-4][0-9]{7}|922337203685[0-3][0-9]{6}|9223372036854[0-6][0-9]{5}|92233720368547[0-6][0-9]{4}|922337203685477[0-4][0-9]{3}|9223372036854775[0-7][0-9]{2}|922337203685477580[0-6]|9223372036854775807)$", "nullable": true } }, "type": "object" }, "InventoryEntryAcknowledgement": { "description": "Empty JSON object acknowledgement", "type": "object" }, "InventoryEntryProblem": { "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "error_code": { "type": "string", "nullable": true }, "errors": { "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" }, "InventoryEntryQuantityProblem": { "description": "A refused quantity: errors marks it under the field it was sent under, inventory_entry_item_quantities. or item_quantities. on the legacy map, the path a validation error uses. Only the first refused line is reported.", "required": [ "title", "status", "detail", "error_code", "errors", "inventory_entry_item_id", "reason", "expected_quantity", "current_quantity_received", "attempted_quantity_received" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "error_code": { "type": "string", "enum": [ "invalid_quantity_update" ] }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "inventory_entry_item_id": { "type": "string", "format": "uuid" }, "reason": { "type": "string", "enum": [ "negative", "exceeds_expected", "cannot_decrease" ] }, "expected_quantity": { "description": "Set when the quantity exceeds the expected one", "type": "string", "nullable": true }, "current_quantity_received": { "description": "Set when the quantity exceeds the expected one or would decrease what was received", "type": "string", "nullable": true }, "attempted_quantity_received": { "type": "string" } }, "type": "object" }, "InventoryEntryUnauthenticated": { "required": [ "message" ], "properties": { "message": { "type": "string" } }, "type": "object" }, "InventoryEntryForbidden": { "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "error_code": { "type": "string", "nullable": true }, "errors": { "type": "object", "nullable": true } }, "type": "object" }, "InventoryEntryAccountingConfigurationError": { "required": [ "error", "missing" ], "properties": { "error": { "type": "string", "enum": [ "accounting_configuration_incomplete" ] }, "missing": { "type": "array", "items": { "required": [ "reason_code", "subject_type", "subject_id", "human_message", "details" ], "properties": { "reason_code": { "type": "string", "example": "OFFICIAL_RATE_NOT_AVAILABLE" }, "subject_type": { "type": "string" }, "subject_id": { "type": "string" }, "human_message": { "type": "string" }, "details": { "description": "For OFFICIAL_RATE_NOT_AVAILABLE: the currency pair and the value date it needs.", "type": "array", "items": { "type": "string" } } }, "type": "object" } } }, "type": "object" }, "ItemSearchItem": { "description": "An active Item as the item search lists it. The three quantity keys are present exactly when location_id is given.", "required": [ "id", "code", "sku", "barcode", "name", "variant_group", "variant_options", "base_unit_id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string", "example": "ITM2600001" }, "sku": { "description": "«SKU», stored as written; null when the Item has none.", "type": "string", "nullable": true }, "barcode": { "description": "«Código de barras», stored as written; null when the Item has none.", "type": "string", "nullable": true }, "name": { "type": "string", "example": "Guantes de nitrilo" }, "variant_group": { "description": "The Modelo the Item is a Variante of; null outside any Modelo.", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "example": "Polo" } }, "type": "object", "nullable": true }, "variant_options": { "description": "Its value for each option of its Modelo, in the Modelo's order; null exactly when variant_group is null.", "type": "array", "items": { "$ref": "#/components/schemas/ItemVariantOption" }, "nullable": true }, "base_unit_id": { "description": "The Item's base unit; null only for an Item without one.", "type": "string", "format": "uuid", "nullable": true }, "on_hand_quantity": { "description": "Existencia at location_id, 0.0000 without a stock row there. Present exactly when location_id is given.", "type": "string", "pattern": "^-?\\d+\\.\\d{4}$", "example": "5.0000" }, "reserved_quantity": { "description": "Reservado at location_id, 0.0000 without a stock row there. Present exactly when location_id is given.", "type": "string", "pattern": "^-?\\d+\\.\\d{4}$", "example": "2.0000" }, "sellable_quantity": { "description": "Disponible at location_id: Existencia minus Reservado, 0.0000 without a stock row there. Present exactly when location_id is given; a negative Disponible is a shortage (ADR 0270).", "type": "string", "pattern": "^-?\\d+\\.\\d{4}$", "example": "3.0000" } }, "type": "object" }, "ItemSearchGroup": { "description": "An active Modelo whose name matched, with every one of its active Variantes in code order.", "required": [ "id", "name", "option_names", "variants" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "example": "Polo" }, "option_names": { "description": "The Modelo's option names in its order, the picker's column headers.", "type": "array", "items": { "type": "string", "example": "Talla" } }, "variants": { "description": "Every active Variante, unpaged; empty when the Modelo has none.", "type": "array", "items": { "$ref": "#/components/schemas/ItemSearchItem" } } }, "type": "object" }, "ItemSearchResult": { "required": [ "match", "items", "groups", "current_page", "per_page", "has_more_items", "has_more_groups" ], "properties": { "match": { "description": "barcode, sku or code: one active Item whose identifier equals q exactly, tried in that order. text: names containing q. none: nothing on page 1 of the text phase.", "type": "string", "enum": [ "barcode", "sku", "code", "text", "none" ] }, "items": { "description": "Prefix matches first, then by name. A Variante of a matching active Modelo is listed only inside its group.", "type": "array", "items": { "$ref": "#/components/schemas/ItemSearchItem" } }, "groups": { "description": "Matching active Modelos, prefix matches first, then by name; always empty for an exact match.", "type": "array", "items": { "$ref": "#/components/schemas/ItemSearchGroup" } }, "current_page": { "description": "Always 1 for an exact match.", "type": "integer", "minimum": 1 }, "per_page": { "type": "integer", "maximum": 50, "minimum": 1 }, "has_more_items": { "type": "boolean" }, "has_more_groups": { "type": "boolean" } }, "type": "object" }, "ItemEmptyResponse": { "description": "Actual empty JSON object returned by successful Item and comment writes.", "type": "object", "additionalProperties": false }, "ItemProblem": { "required": [ "title", "status", "detail" ], "properties": { "title": { "type": "string" }, "detail": { "type": "string" }, "status": { "type": "integer" }, "error_code": { "type": "string", "nullable": true }, "errors": { "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "missing_options": { "description": "Present only for item_variant_options_mismatch: the Modelo's options the request gave no value for.", "type": "array", "items": { "type": "string" } }, "unexpected_options": { "description": "Present only for item_variant_options_mismatch: the option names the Modelo lacks or that were given twice.", "type": "array", "items": { "type": "string" } } }, "type": "object" }, "ItemVariantOption": { "description": "One option of a Variante: the Modelo's option name and the Item's value for it.", "required": [ "name", "value" ], "properties": { "name": { "type": "string", "example": "Talla", "maxLength": 40 }, "value": { "type": "string", "example": "M", "maxLength": 60 } }, "type": "object" }, "ItemMiddlewareError": { "required": [ "message" ], "properties": { "message": { "type": "string" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" }, "ItemError": { "oneOf": [ { "$ref": "#/components/schemas/ItemProblem" }, { "$ref": "#/components/schemas/ItemMiddlewareError" } ] }, "ItemConflict": { "description": "An Item write refused by a unique rule: a duplicate normalized name in the category, a barcode or SKU another active Item of the company uses (ADR 0274), or a combination of values another Item of the Modelo, in any status, holds ignoring letter case (ADR 0273). On update, item_concurrently_modified means another request changed the Item's Modelo membership after this one read it; reload and retry.", "required": [ "title", "status", "detail", "error_code" ], "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "detail": { "type": "string", "example": "El código de barras '7591234567890' ya lo usa el artículo ITM2600001 Guantes de nitrilo" }, "error_code": { "type": "string", "enum": [ "duplicate_item_name", "item_barcode_already_used", "item_sku_already_used", "item_variant_combination_taken", "item_concurrently_modified" ] }, "errors": { "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "existing_item": { "description": "The Item that already holds the value: the active Item using the barcode or SKU, or the Item of the Modelo, in any status, holding the combination. Present for item_barcode_already_used, item_sku_already_used and item_variant_combination_taken, null when a concurrent change left it unnameable; absent for duplicate_item_name and item_concurrently_modified.", "required": [ "id", "code", "name" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string", "example": "ITM2600001" }, "name": { "type": "string", "example": "Guantes de nitrilo" } }, "type": "object", "nullable": true } }, "type": "object" }, "ItemLabel": { "required": [ "id", "name", "tone", "archived" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "tone": { "type": "string", "enum": [ "red", "orange", "blue", "violet", "teal" ] }, "archived": { "type": "boolean" } }, "type": "object" }, "ItemAccount": { "required": [ "id", "accounting_account_id", "type" ], "properties": { "id": { "type": "string", "format": "uuid" }, "accounting_account_id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "asset", "liability", "equity", "revenue", "cost", "expense" ] } }, "type": "object" }, "ItemUnit": { "required": [ "id", "item_id", "unit_id", "company_id", "conversion_factor", "is_base_unit", "unit_name" ], "properties": { "id": { "type": "string", "format": "uuid" }, "item_id": { "type": "string", "format": "uuid" }, "unit_id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "conversion_factor": { "description": "Positive decimal string; exactly one base unit.", "type": "string", "pattern": "^\\d{1,6}(\\.\\d{1,4})?$" }, "is_base_unit": { "type": "boolean" }, "unit_name": { "description": "Name of the unit of measure; null only when the unit record no longer exists.", "type": "string", "nullable": true } }, "type": "object" }, "ItemSummaryImage": { "required": [ "id", "thumbnail_url", "original_url", "is_primary", "alt_text", "file_size", "width", "height" ], "properties": { "id": { "type": "string", "format": "uuid" }, "thumbnail_url": { "type": "string" }, "original_url": { "type": "string" }, "is_primary": { "type": "boolean" }, "alt_text": { "type": "string", "nullable": true }, "file_size": { "type": "integer" }, "width": { "type": "integer", "nullable": true }, "height": { "type": "integer", "nullable": true } }, "type": "object" }, "ItemImage": { "required": [ "id", "thumbnail_url", "original_url", "is_primary", "alt_text", "file_size", "width", "height", "item_id", "original_filename", "storage_path", "mime_type", "sort_order" ], "properties": { "id": { "type": "string", "format": "uuid" }, "thumbnail_url": { "type": "string" }, "original_url": { "type": "string" }, "is_primary": { "type": "boolean" }, "alt_text": { "type": "string", "nullable": true }, "file_size": { "type": "integer" }, "width": { "type": "integer", "nullable": true }, "height": { "type": "integer", "nullable": true }, "item_id": { "type": "string", "format": "uuid" }, "original_filename": { "type": "string" }, "storage_path": { "type": "string" }, "mime_type": { "type": "string" }, "sort_order": { "type": "integer" } }, "type": "object" }, "ItemListRow": { "required": [ "id", "company_id", "category_id", "code", "name", "status", "type", "default_islr_classification", "default_sales_tax_id", "default_purchase_tax_id", "barcode", "sku", "sale_price", "variant_group_id", "variant_options", "accounts", "average_cost", "reporting_average_cost", "available_quantity", "in_transfer", "total_value", "reporting_total_value", "functional_currency", "reporting_currency", "labels", "name_normalized" ], "properties": { "id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "category_id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "type": { "type": "string", "enum": [ "inventoried", "non-inventoried" ] }, "default_islr_classification": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,63}$", "nullable": true, "maxLength": 64 }, "default_sales_tax_id": { "description": "«Impuesto de venta por defecto»: the catalog tax a counter-sale line of the Item takes; null when the Item names none, and such an Item cannot be sold at the counter.", "type": "string", "format": "uuid", "nullable": true }, "default_purchase_unit_id": { "description": "Own-item unit proposed for purchases; null clears, omission preserves on update. Removing its item unit clears the reference.", "type": "string", "format": "uuid", "nullable": true }, "default_sales_unit_id": { "description": "Own-item unit proposed for sales; null clears, omission preserves on update. A foreign unit answers 422 item_default_unit_invalid.", "type": "string", "format": "uuid", "nullable": true }, "default_purchase_tax_id": { "description": "«Impuesto de compra por defecto»: the catalog tax purchase documents propose from this Item; null when the Item names none,.", "type": "string", "format": "uuid", "nullable": true }, "barcode": { "description": "«Código de barras», stored as written; null when the Item has none.", "type": "string", "nullable": true, "maxLength": 64 }, "sku": { "description": "«SKU», stored as written; null when the Item has none.", "type": "string", "nullable": true, "maxLength": 64 }, "sale_price": { "description": "Precio base per base unit; null when the Item has none.", "required": [ "amount", "currency" ], "properties": { "amount": { "type": "string", "pattern": "^\\d{1,13}\\.\\d{2}$", "example": "12.50" }, "currency": { "type": "string", "enum": [ "USD", "VES" ] } }, "type": "object", "nullable": true }, "variant_group_id": { "description": "The Modelo the Item is a Variante of; null outside any Modelo.", "type": "string", "format": "uuid", "nullable": true }, "variant_options": { "description": "Its value for each option of its Modelo, in the Modelo's order; null exactly when variant_group_id is null.", "type": "array", "items": { "$ref": "#/components/schemas/ItemVariantOption" }, "nullable": true }, "accounts": { "type": "array", "items": { "$ref": "#/components/schemas/ItemAccount" } }, "average_cost": { "type": "string", "example": "0.0000" }, "reporting_average_cost": { "type": "string", "example": "0.0000" }, "available_quantity": { "type": "string", "example": "0.0000" }, "reserved_quantity": { "type": "string", "example": "0.0000" }, "pending_receipt_quantity": { "description": "Approved purchase quantities not yet received, in item base units.", "type": "string", "example": "18.0000" }, "sellable_quantity": { "type": "string", "example": "-2.0000" }, "in_transfer": { "type": "string", "example": "0.0000" }, "total_value": { "description": "What the inventory account holds for the item in the functional book, its carrying value. It includes the stock transfers have in transit, which available_quantity leaves out, so it can differ from available_quantity × average_cost.", "type": "string", "example": "0.00" }, "reporting_total_value": { "description": "What the inventory account holds for the item in the reporting book, its carrying value. It includes the stock transfers have in transit, which available_quantity leaves out, so it can differ from available_quantity × reporting_average_cost.", "type": "string", "example": "0.00" }, "functional_currency": { "type": "string" }, "reporting_currency": { "type": "string" }, "labels": { "type": "array", "items": { "$ref": "#/components/schemas/ItemLabel" } }, "name_normalized": { "type": "string" } }, "type": "object" }, "ItemResource": { "required": [ "id", "company_id", "category_id", "code", "name", "status", "type", "default_islr_classification", "default_sales_tax_id", "default_purchase_tax_id", "barcode", "sku", "sale_price", "variant_group_id", "variant_options", "accounts", "average_cost", "reporting_average_cost", "available_quantity", "in_transfer", "total_value", "reporting_total_value", "functional_currency", "reporting_currency", "labels", "units", "has_transactions", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "category_id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "type": { "type": "string", "enum": [ "inventoried", "non-inventoried" ] }, "default_islr_classification": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,63}$", "nullable": true, "maxLength": 64 }, "default_sales_tax_id": { "description": "«Impuesto de venta por defecto»: the catalog tax a counter-sale line of the Item takes; null when the Item names none, and such an Item cannot be sold at the counter.", "type": "string", "format": "uuid", "nullable": true }, "default_purchase_unit_id": { "description": "Own-item unit proposed for purchases; null clears, omission preserves on update. Removing its item unit clears the reference.", "type": "string", "format": "uuid", "nullable": true }, "default_sales_unit_id": { "description": "Own-item unit proposed for sales; null clears, omission preserves on update. A foreign unit answers 422 item_default_unit_invalid.", "type": "string", "format": "uuid", "nullable": true }, "default_purchase_tax_id": { "description": "«Impuesto de compra por defecto»: the catalog tax purchase documents propose from this Item; null when the Item names none,.", "type": "string", "format": "uuid", "nullable": true }, "barcode": { "description": "«Código de barras», stored as written; null when the Item has none.", "type": "string", "nullable": true, "maxLength": 64 }, "sku": { "description": "«SKU», stored as written; null when the Item has none.", "type": "string", "nullable": true, "maxLength": 64 }, "sale_price": { "description": "Precio base per base unit; null when the Item has none.", "required": [ "amount", "currency" ], "properties": { "amount": { "type": "string", "pattern": "^\\d{1,13}\\.\\d{2}$", "example": "12.50" }, "currency": { "type": "string", "enum": [ "USD", "VES" ] } }, "type": "object", "nullable": true }, "variant_group_id": { "description": "The Modelo the Item is a Variante of; null outside any Modelo.", "type": "string", "format": "uuid", "nullable": true }, "variant_options": { "description": "Its value for each option of its Modelo, in the Modelo's order; null exactly when variant_group_id is null.", "type": "array", "items": { "$ref": "#/components/schemas/ItemVariantOption" }, "nullable": true }, "accounts": { "type": "array", "items": { "$ref": "#/components/schemas/ItemAccount" } }, "average_cost": { "type": "string", "example": "0.0000" }, "reporting_average_cost": { "type": "string", "example": "0.0000" }, "available_quantity": { "type": "string", "example": "0.0000" }, "in_transfer": { "type": "string", "example": "0.0000" }, "total_value": { "description": "What the inventory account holds for the item in the functional book, its carrying value. It includes the stock transfers have in transit, which available_quantity leaves out, so it can differ from available_quantity × average_cost.", "type": "string", "example": "0.00" }, "reporting_total_value": { "description": "What the inventory account holds for the item in the reporting book, its carrying value. It includes the stock transfers have in transit, which available_quantity leaves out, so it can differ from available_quantity × reporting_average_cost.", "type": "string", "example": "0.00" }, "functional_currency": { "type": "string" }, "reporting_currency": { "type": "string" }, "labels": { "type": "array", "items": { "$ref": "#/components/schemas/ItemLabel" } }, "units": { "type": "array", "items": { "$ref": "#/components/schemas/ItemUnit" } }, "has_transactions": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time", "nullable": true }, "updated_at": { "type": "string", "format": "date-time", "nullable": true }, "images": { "type": "array", "items": { "$ref": "#/components/schemas/ItemSummaryImage" } } }, "type": "object" }, "ItemStatusCounts": { "required": [ "active", "inactive" ], "properties": { "active": { "type": "integer", "minimum": 0 }, "inactive": { "type": "integer", "minimum": 0 } }, "type": "object" }, "ItemListMeta": { "required": [ "counts", "label_counts" ], "properties": { "counts": { "$ref": "#/components/schemas/ItemStatusCounts" }, "label_counts": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 0 } } }, "type": "object" }, "ItemPage": { "required": [ "items", "total", "per_page", "current_page", "meta" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ItemListRow" } }, "total": { "type": "integer" }, "per_page": { "type": "integer" }, "current_page": { "type": "integer" }, "meta": { "$ref": "#/components/schemas/ItemListMeta" } }, "type": "object" }, "ItemImagePage": { "required": [ "images", "total", "page", "limit", "has_more" ], "properties": { "images": { "type": "array", "items": { "$ref": "#/components/schemas/ItemImage" } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "limit": { "type": "integer" }, "has_more": { "type": "boolean" } }, "type": "object" }, "ItemImageUpload": { "required": [ "id", "status", "thumbnail_url", "message" ], "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "thumbnail_url": { "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "ItemComment": { "required": [ "id", "body", "author_user_id", "created_at", "updated_at", "edited_at", "can_edit", "can_delete", "mentions" ], "properties": { "id": { "type": "string", "format": "uuid" }, "body": { "type": "string", "maxLength": 5000 }, "author_user_id": { "type": "integer" }, "mentions": { "type": "array", "items": { "required": [ "user_id", "name" ], "properties": { "user_id": { "type": "integer" }, "name": { "type": "string" } }, "type": "object" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "edited_at": { "type": "string", "format": "date-time", "nullable": true }, "parent_id": { "type": "string", "format": "uuid", "nullable": true }, "is_deleted": { "type": "boolean" }, "can_edit": { "type": "boolean" }, "can_delete": { "type": "boolean" } }, "type": "object" }, "ItemComments": { "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ItemComment" } } }, "type": "object" }, "ItemAccountInput": { "required": [ "accounting_account_id", "type" ], "properties": { "accounting_account_id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "asset", "liability", "equity", "revenue", "cost", "expense" ] } }, "type": "object" }, "ItemUnitInput": { "required": [ "unit_id", "conversion_factor" ], "properties": { "unit_id": { "type": "string", "format": "uuid" }, "conversion_factor": { "description": "Positive decimal string; exactly one base unit.", "type": "string", "pattern": "^\\d{1,6}(\\.\\d{1,4})?$" }, "is_base_unit": { "type": "boolean" }, "action": { "description": "Update only; omitted on create.", "type": "string", "enum": [ "add", "remove", "update" ] } }, "type": "object" }, "ItemCreateInput": { "required": [ "id", "name", "category_id", "accounts", "units" ], "properties": { "id": { "type": "string", "format": "uuid" }, "category_id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "maxLength": 80, "minLength": 3 }, "type": { "type": "string", "enum": [ "inventoried", "non-inventoried" ] }, "default_islr_classification": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,63}$", "nullable": true, "maxLength": 64 }, "default_sales_tax_id": { "description": "«Impuesto de venta por defecto»: an active tax of the company that a counter-sale line of the Item takes. Omit or null for none. A missing, inactive or foreign tax answers 422 item_default_sales_tax_invalid.", "type": "string", "format": "uuid", "nullable": true }, "default_purchase_unit_id": { "description": "Own-item unit proposed for purchases; null clears, omission preserves on update. Removing its item unit clears the reference.", "type": "string", "format": "uuid", "nullable": true }, "default_sales_unit_id": { "description": "Own-item unit proposed for sales; null clears, omission preserves on update. A foreign unit answers 422 item_default_unit_invalid.", "type": "string", "format": "uuid", "nullable": true }, "default_purchase_tax_id": { "description": "«Impuesto de compra por defecto»: an active tax of the company that purchase documents propose from this Item. Omit or null for none. A missing, inactive or foreign tax answers 422 item_default_purchase_tax_invalid.", "type": "string", "format": "uuid", "nullable": true }, "barcode": { "description": "«Código de barras». Opaque: trimmed and stored as written, never parsed. Absent, null or blank means none; on multipart omit the key when empty. Unique per company among active Items: a collision answers 409 item_barcode_already_used.", "type": "string", "nullable": true, "maxLength": 64 }, "sku": { "description": "«SKU». Opaque: trimmed and stored as written, never parsed. Absent, null or blank means none; on multipart omit the key when empty. Unique per company among active Items: a collision answers 409 item_sku_already_used.", "type": "string", "nullable": true, "maxLength": 64 }, "sale_price": { "description": "Precio base per base unit, stored at exactly 2 decimals. Omit or null for none; in multipart/form-data send sale_price[amount] and sale_price[currency].", "required": [ "amount", "currency" ], "properties": { "amount": { "type": "string", "pattern": "^\\d{1,13}(\\.\\d{1,2})?$", "example": "12.50" }, "currency": { "type": "string", "enum": [ "USD", "VES" ] } }, "type": "object", "nullable": true, "additionalProperties": false }, "variant_group_id": { "description": "A Modelo of the company, active, the Item becomes a Variante of. Omit or null for none; variant_options is then refused unless omitted.", "type": "string", "format": "uuid", "nullable": true }, "variant_options": { "description": "Required with variant_group_id: exactly one {name, value} per option of the Modelo, in any order, names matched ignoring letter case and spacing; stored in the Modelo's order and spelling. Prohibited without a Modelo. In multipart/form-data send variant_options[i][name] and variant_options[i][value].", "type": "array", "items": { "$ref": "#/components/schemas/ItemVariantOption" }, "nullable": true, "maxItems": 3 }, "accounts": { "type": "array", "items": { "$ref": "#/components/schemas/ItemAccountInput" }, "minItems": 1 }, "units": { "type": "array", "items": { "$ref": "#/components/schemas/ItemUnitInput" }, "minItems": 1 } }, "type": "object" }, "ItemUpdateInput": { "required": [ "name", "accounts" ], "properties": { "name": { "type": "string", "maxLength": 80, "minLength": 3 }, "category_id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "inventoried", "non-inventoried" ] }, "default_islr_classification": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,63}$", "nullable": true, "maxLength": 64 }, "default_sales_tax_id": { "description": "«Impuesto de venta por defecto»: an active tax of the company that a counter-sale line of the Item takes. Omitted keeps the stored one; null clears it. A missing, inactive or foreign tax answers 422 item_default_sales_tax_invalid.", "type": "string", "format": "uuid", "nullable": true }, "default_purchase_unit_id": { "description": "Own-item unit proposed for purchases; null clears, omission preserves on update. Removing its item unit clears the reference.", "type": "string", "format": "uuid", "nullable": true }, "default_sales_unit_id": { "description": "Own-item unit proposed for sales; null clears, omission preserves on update. A foreign unit answers 422 item_default_unit_invalid.", "type": "string", "format": "uuid", "nullable": true }, "default_purchase_tax_id": { "description": "«Impuesto de compra por defecto»: an active tax of the company that purchase documents propose from this Item. Omitted keeps the stored one; null clears it. A missing, inactive or foreign tax answers 422 item_default_purchase_tax_invalid.", "type": "string", "format": "uuid", "nullable": true }, "barcode": { "description": "«Código de barras». Omitted keeps the stored one; null or blank clears it; a string sets it, trimmed and stored as written. Unique per company among active Items: a collision answers 409 item_barcode_already_used.", "type": "string", "nullable": true, "maxLength": 64 }, "sku": { "description": "«SKU». Omitted keeps the stored one; null or blank clears it; a string sets it, trimmed and stored as written. Unique per company among active Items: a collision answers 409 item_sku_already_used.", "type": "string", "nullable": true, "maxLength": 64 }, "sale_price": { "description": "Precio base per base unit, stored at exactly 2 decimals. Omitted keeps the stored Precio base; null clears it.", "required": [ "amount", "currency" ], "properties": { "amount": { "type": "string", "pattern": "^\\d{1,13}(\\.\\d{1,2})?$", "example": "12.50" }, "currency": { "type": "string", "enum": [ "USD", "VES" ] } }, "type": "object", "nullable": true, "additionalProperties": false }, "variant_group_id": { "description": "Omitted keeps the Item's Modelo and values (variant_options must be omitted too); null leaves the Modelo and frees its combination; a UUID joins, switches to or stays in that Modelo. Joining or switching to an inactive Modelo is refused; staying in one is allowed.", "type": "string", "format": "uuid", "nullable": true }, "variant_options": { "description": "Required with a variant_group_id: exactly one {name, value} per option of the Modelo, in any order, names matched ignoring letter case and spacing. Null, omitted or [] when variant_group_id is null; prohibited when variant_group_id is omitted.", "type": "array", "items": { "$ref": "#/components/schemas/ItemVariantOption" }, "nullable": true, "maxItems": 3 }, "accounts": { "type": "array", "items": { "$ref": "#/components/schemas/ItemAccountInput" }, "minItems": 1 }, "units": { "type": "array", "items": { "$ref": "#/components/schemas/ItemUnitInput" } }, "status": { "type": "string", "enum": [ "active", "inactive" ] } }, "type": "object" }, "ItemPurchaseTaxProposal": { "required": [ "id", "name", "rate", "kind" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "rate": { "type": "string" }, "kind": { "type": "string" } }, "type": "object" }, "LocationValidationProblem": { "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string", "example": "The given data was invalid." }, "error_code": { "type": "string", "nullable": true }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" }, "InsufficientStockItem": { "description": "An item at a location whose Disponible does not cover what the approval asks to reserve there (MER-3872).", "required": [ "item_id", "location_id", "requested_quantity", "sellable_quantity" ], "properties": { "item_id": { "type": "string", "format": "uuid" }, "location_id": { "type": "string", "format": "uuid" }, "requested_quantity": { "description": "Base-unit total the approval asks to reserve for this item at this location, across all its lines.", "type": "string", "example": "3.0000" }, "sellable_quantity": { "description": "Disponible under the stock lock: Existencia minus Cantidad reservada. It can be negative.", "type": "string", "example": "1.0000" }, "base_unit_name": { "description": "The item's base unit, the unit both quantities are in; null when the item has none.", "type": "string", "example": "Kilogramo", "nullable": true } }, "type": "object" }, "InsufficientStockProblem": { "description": "Approval refused because Disponible does not cover every line (insufficient_stock, ADR 0270). Nothing is approved, dispatched or reserved. Only while reserving on approval is switched on.", "required": [ "title", "status", "detail", "error_code", "errors", "insufficient_stock_items" ], "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "detail": { "type": "string" }, "error_code": { "type": "string", "enum": [ "insufficient_stock" ] }, "errors": { "type": "object", "example": null, "nullable": true }, "insufficient_stock_items": { "type": "array", "items": { "$ref": "#/components/schemas/InsufficientStockItem" }, "minItems": 1 } }, "type": "object" }, "InventorySettingsValidationProblem": { "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string", "example": "The given data was invalid." }, "error_code": { "type": "string", "nullable": true }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" }, "InventorySettingsControllerProblem": { "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "error_code": { "type": "string", "nullable": true }, "errors": { "type": "object", "nullable": true } }, "type": "object" }, "InventorySettingsForbidden": { "required": [ "title", "status", "detail" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer", "example": 403 }, "detail": { "type": "string" } }, "type": "object" }, "InventoryTransferItem": { "required": [ "id", "inventory_transfer_id", "item_id", "category_id", "expected_quantity", "unit_id", "origin_location_id", "destination_location_id", "company_id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "inventory_transfer_id": { "type": "string", "format": "uuid" }, "item_id": { "type": "string", "format": "uuid" }, "category_id": { "type": "string", "format": "uuid" }, "expected_quantity": { "description": "DECIMAL(15,4) numeric string; max 11 integer digits and 4 fractional digits", "type": "string", "pattern": "^\\d{1,11}(\\.\\d{1,4})?$", "example": "5.0000" }, "unit_id": { "type": "string", "format": "uuid" }, "origin_location_id": { "type": "string", "format": "uuid" }, "destination_location_id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "item_name": { "type": "string", "nullable": true }, "category_name": { "type": "string", "nullable": true }, "unit_name": { "type": "string", "nullable": true } }, "type": "object" }, "InventoryTransferResource": { "required": [ "id", "code", "status", "date", "company_id", "origin_location_id", "destination_location_id", "responsible_user_id", "items" ], "properties": { "guide_number": { "type": "string", "nullable": true }, "guide_control": { "type": "string", "nullable": true }, "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "in_transit", "received", "cancelled" ] }, "date": { "type": "string" }, "company_id": { "type": "string", "format": "uuid" }, "origin_location_id": { "type": "string", "format": "uuid" }, "destination_location_id": { "type": "string", "format": "uuid" }, "user_id": { "type": "string", "nullable": true }, "responsible_user_id": { "type": "string", "nullable": true }, "responsible_user_name": { "type": "string", "nullable": true }, "labels": { "type": "array", "items": { "required": [ "id", "name", "tone", "archived" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "tone": { "type": "string" }, "archived": { "type": "boolean" } }, "type": "object" } }, "observations": { "type": "string", "nullable": true }, "delivery_date": { "type": "string", "nullable": true }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/InventoryTransferItem" } }, "origin_location_name": { "type": "string", "nullable": true }, "destination_location_name": { "type": "string", "nullable": true }, "user_name": { "type": "string", "nullable": true } }, "type": "object" }, "InventoryTransferEnhancedResource": { "allOf": [ { "$ref": "#/components/schemas/InventoryTransferResource" }, { "required": [ "dispatch", "entry" ], "properties": { "dispatch": { "required": [ "id", "code", "status" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "partial", "completed", "cancelled" ] } }, "type": "object", "nullable": true }, "entry": { "required": [ "id", "code", "status" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "partial", "completed", "cancelled" ] } }, "type": "object", "nullable": true } }, "type": "object" } ] }, "InventoryTransfersPage": { "required": [ "transfers", "total", "perPage", "currentPage", "meta" ], "properties": { "transfers": { "type": "array", "items": { "$ref": "#/components/schemas/InventoryTransferResource" } }, "total": { "type": "integer", "minimum": 0 }, "perPage": { "type": "integer", "maximum": 100, "minimum": 1 }, "currentPage": { "type": "integer", "minimum": 1 }, "meta": { "required": [ "counts", "label_counts" ], "properties": { "counts": { "required": [ "pending", "in_transit", "received", "cancelled" ], "properties": { "pending": { "type": "integer", "minimum": 0 }, "in_transit": { "type": "integer", "minimum": 0 }, "received": { "type": "integer", "minimum": 0 }, "cancelled": { "type": "integer", "minimum": 0 } }, "type": "object" }, "label_counts": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 0 } } }, "type": "object" } }, "type": "object" }, "InventoryTransferProblem": { "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "detail": { "type": "string" }, "error_code": { "type": "string", "example": "inventory_transfer_cannot_be_cancelled", "nullable": true }, "errors": { "type": "object", "nullable": true } }, "type": "object" }, "InventoryTransferUnauthenticated": { "description": "Laravel Sanctum auth:sanctum JSON response for AuthenticationException", "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" }, "InventoryTransferForbidden": { "required": [ "title", "status", "detail" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer", "example": 403 }, "detail": { "type": "string" } }, "type": "object" }, "InventoryTransferResponsibleAcknowledgement": { "description": "Empty JSON object for changed and valid no-op requests", "type": "object" }, "TransformationLabel": { "required": [ "id", "name", "tone", "archived" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "tone": { "type": "string" }, "archived": { "description": "An archived label stays visible on the documents that carry it", "type": "boolean" } }, "type": "object" }, "TransformationLine": { "required": [ "id", "item_id", "item_name", "type", "expected_quantity", "consumed_quantity", "produced_quantity", "unit_cost", "total_cost", "reporting_unit_cost", "reporting_total_cost", "company_id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "item_id": { "type": "string", "format": "uuid" }, "item_name": { "description": "Null when the item is no longer available", "type": "string", "nullable": true }, "type": { "type": "string", "enum": [ "input", "output" ] }, "expected_quantity": { "description": "Exact DECIMAL(24,8) string", "type": "string", "example": "10.00000000" }, "consumed_quantity": { "description": "Exact DECIMAL(24,8) string; inputs only, 0 on outputs", "type": "string", "example": "0.00000000" }, "produced_quantity": { "description": "Exact DECIMAL(24,8) string; outputs only, 0 on inputs", "type": "string", "example": "0.00000000" }, "unit_cost": { "description": "Cost of one unit in the functional book, scale 8. Null before the line is valued.", "type": "string", "example": "1133.33333333", "nullable": true }, "total_cost": { "description": "Cost of the line's quantity in the functional book, scale 8. Null before the line is valued.", "type": "string", "example": "3400.00000000", "nullable": true }, "reporting_unit_cost": { "description": "Cost of one unit in the reporting book, scale 8. Null before the line is valued or for a line processed before MER-3710.", "type": "string", "example": "10.00000000", "nullable": true }, "reporting_total_cost": { "description": "Cost of the line's quantity in the reporting book, scale 8. Null before the line is valued or for a line processed before MER-3710.", "type": "string", "example": "30.00000000", "nullable": true }, "company_id": { "type": "string", "format": "uuid" } }, "type": "object" }, "TransformationResource": { "description": "A list row and the record share this shape.", "required": [ "id", "code", "date", "input_location_id", "output_location_id", "location_id", "input_location_name", "output_location_name", "responsible_user_id", "responsible_user_name", "status", "company_id", "version", "lines", "input_total_cost", "output_total_cost", "reporting_input_total_cost", "reporting_output_total_cost", "created_at", "updated_at", "processed_at", "canceled_at", "processed_by", "canceled_by", "inputs_count", "outputs_count", "first_output_item_name", "labels" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string", "example": "TRN2600012" }, "date": { "type": "string", "format": "date", "example": "2026-10-13" }, "input_location_id": { "type": "string", "format": "uuid" }, "output_location_id": { "type": "string", "format": "uuid" }, "location_id": { "description": "The input location, kept for compatibility; read input_location_id", "type": "string", "format": "uuid", "deprecated": true }, "input_location_name": { "type": "string", "nullable": true }, "output_location_name": { "type": "string", "nullable": true }, "responsible_user_id": { "description": "Required Responsable; it changes only through PUT /{id}/responsible", "type": "integer", "minimum": 1 }, "responsible_user_name": { "description": "Null means the user is no longer available", "type": "string", "nullable": true }, "status": { "description": "Only por_aprobar and en_proceso take edits", "type": "string", "enum": [ "por_aprobar", "en_proceso", "procesada", "anulada" ] }, "company_id": { "type": "string", "format": "uuid" }, "version": { "description": "Send it back unchanged on the next write; take the next one from the write's response or refetch, never compute it", "type": "integer", "minimum": 1 }, "lines": { "description": "In ascending line id", "type": "array", "items": { "$ref": "#/components/schemas/TransformationLine" } }, "input_total_cost": { "description": "Sum of the inputs' functional total costs, scale 8.", "type": "string", "example": "3400.00000000" }, "output_total_cost": { "description": "Sum of the outputs' functional total costs, scale 8.", "type": "string", "example": "3400.00000000" }, "reporting_input_total_cost": { "description": "Sum of the inputs' reporting total costs, scale 8. Null while no input carries a reporting cost.", "type": "string", "example": "30.00000000", "nullable": true }, "reporting_output_total_cost": { "description": "Sum of the outputs' reporting total costs, scale 8. Null while no output carries a reporting cost.", "type": "string", "example": "30.00000000", "nullable": true }, "created_at": { "description": "UTC as Y-m-d H:i:s; parse it as UTC", "type": "string", "example": "2026-10-13 14:00:00", "nullable": true }, "updated_at": { "description": "UTC as Y-m-d H:i:s; parse it as UTC", "type": "string", "example": "2026-10-13 15:10:00", "nullable": true }, "processed_at": { "description": "UTC as Y-m-d H:i:s", "type": "string", "nullable": true }, "canceled_at": { "description": "UTC as Y-m-d H:i:s", "type": "string", "nullable": true }, "processed_by": { "type": "string", "nullable": true }, "canceled_by": { "type": "string", "nullable": true }, "inputs_count": { "type": "integer", "minimum": 0 }, "outputs_count": { "type": "integer", "minimum": 0 }, "first_output_item_name": { "description": "Name of the first output in line order; null when it has none", "type": "string", "nullable": true }, "labels": { "type": "array", "items": { "$ref": "#/components/schemas/TransformationLabel" } } }, "type": "object" }, "TransformationsPage": { "required": [ "data", "total", "per_page", "current_page", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TransformationResource" } }, "total": { "description": "Rows that match every filter", "type": "integer", "minimum": 0 }, "per_page": { "type": "integer", "maximum": 100, "minimum": 1 }, "current_page": { "type": "integer", "minimum": 1 }, "meta": { "required": [ "counts", "label_counts" ], "properties": { "counts": { "description": "Rows per status under every filter except status", "required": [ "por_aprobar", "en_proceso", "procesada", "anulada" ], "properties": { "por_aprobar": { "type": "integer", "minimum": 0 }, "en_proceso": { "type": "integer", "minimum": 0 }, "procesada": { "type": "integer", "minimum": 0 }, "anulada": { "type": "integer", "minimum": 0 } }, "type": "object" }, "label_counts": { "description": "Distinct rows per active label under every filter except label_ids; {} when none", "type": "object", "additionalProperties": { "type": "integer", "minimum": 0 } } }, "type": "object" } }, "type": "object" }, "TransformationCreateRequest": { "required": [ "date", "input_location_id", "output_location_id", "responsible_user_id", "lines" ], "properties": { "date": { "type": "string", "format": "date", "example": "2026-10-13" }, "input_location_id": { "type": "string", "format": "uuid" }, "output_location_id": { "type": "string", "format": "uuid" }, "responsible_user_id": { "type": "integer", "minimum": 1 }, "lines": { "description": "At least one input and one output", "type": "array", "items": { "required": [ "item_id", "type", "expected_quantity" ], "properties": { "item_id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "input", "output" ] }, "expected_quantity": { "description": "Positive number or DECIMAL(24,8) string. Only a JSON string preserves the exact scale.", "oneOf": [ { "type": "number", "maximum": 10000000000000000, "minimum": 1.0e-8 }, { "type": "string", "pattern": "^(?!0+(?:\\.0+)?$)\\d{1,16}(?:\\.\\d{1,8})?$", "example": "2.50000000" } ] } }, "type": "object" }, "minItems": 2 } }, "type": "object" }, "TransformationCreated": { "required": [ "id", "code", "date", "input_location_id", "output_location_id", "responsible_user_id", "status", "company_id", "version", "lines", "created_at", "updated_at" ], "properties": { "id": { "description": "Navigate with it; read the code from the record", "type": "string", "format": "uuid" }, "code": { "type": "string", "example": "TRN2600012" }, "date": { "type": "string", "format": "date" }, "input_location_id": { "type": "string", "format": "uuid" }, "output_location_id": { "type": "string", "format": "uuid" }, "responsible_user_id": { "description": "The Responsable id as a string here; the record returns an integer", "type": "string", "example": "42" }, "status": { "type": "string", "enum": [ "por_aprobar" ] }, "company_id": { "type": "string", "format": "uuid" }, "version": { "type": "integer", "enum": [ 1 ] }, "lines": { "type": "array", "items": { "required": [ "id", "item_id", "type", "expected_quantity" ], "properties": { "id": { "type": "string", "format": "uuid" }, "item_id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "input", "output" ] }, "expected_quantity": { "description": "Echoes the value sent", "oneOf": [ { "type": "number" }, { "type": "string" } ] } }, "type": "object" } }, "created_at": { "type": "string", "example": "2026-10-13 14:00:00" }, "updated_at": { "type": "string", "example": "2026-10-13 14:00:00" } }, "type": "object" }, "TransformationHeaderRequest": { "required": [ "date", "input_location_id", "output_location_id", "version" ], "properties": { "date": { "type": "string", "format": "date", "example": "2026-10-13" }, "input_location_id": { "type": "string", "format": "uuid" }, "output_location_id": { "type": "string", "format": "uuid" }, "responsible_user_id": { "description": "Accepted and ignored; reassign through PUT /{id}/responsible", "deprecated": true }, "version": { "type": "integer", "minimum": 1 } }, "type": "object" }, "TransformationCompleteRequest": { "required": [ "date", "input_location_id", "output_location_id", "lines", "version" ], "properties": { "date": { "type": "string", "format": "date", "example": "2026-10-13" }, "input_location_id": { "type": "string", "format": "uuid" }, "output_location_id": { "type": "string", "format": "uuid" }, "responsible_user_id": { "description": "Accepted and ignored; reassign through PUT /{id}/responsible", "deprecated": true }, "lines": { "description": "Replaces every line; at least one input and one output, distinct ids", "type": "array", "items": { "required": [ "id", "item_id", "type", "expected_quantity" ], "properties": { "id": { "type": "string", "format": "uuid" }, "item_id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "input", "output" ] }, "expected_quantity": { "description": "Positive DECIMAL(24,8) string", "type": "string", "pattern": "^(?!0+(?:\\.0+)?$)\\d{1,16}(?:\\.\\d{1,8})?$", "example": "2.50000000" } }, "type": "object" }, "minItems": 1 }, "version": { "type": "integer", "minimum": 1 } }, "type": "object" }, "TransformationHeaderUpdated": { "required": [ "id", "code", "date", "input_location_id", "output_location_id", "responsible_user_id", "status", "version", "updated_at", "message" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "date": { "type": "string", "format": "date" }, "input_location_id": { "type": "string", "format": "uuid" }, "output_location_id": { "type": "string", "format": "uuid" }, "responsible_user_id": { "description": "Unchanged by this write", "type": "integer", "minimum": 1 }, "status": { "type": "string", "enum": [ "por_aprobar", "en_proceso" ] }, "version": { "description": "The next version to send", "type": "integer", "minimum": 1 }, "updated_at": { "type": "string", "nullable": true }, "message": { "type": "string" } }, "type": "object" }, "TransformationCompleted": { "required": [ "id", "code", "date", "input_location_id", "output_location_id", "responsible_user_id", "status", "version", "updated_at", "lines_count", "message" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "date": { "type": "string", "format": "date" }, "input_location_id": { "type": "string", "format": "uuid" }, "output_location_id": { "type": "string", "format": "uuid" }, "responsible_user_id": { "description": "Unchanged by this write", "type": "integer", "minimum": 1 }, "status": { "type": "string", "enum": [ "por_aprobar", "en_proceso" ] }, "version": { "description": "The next version to send; the edit moves it by 2", "type": "integer", "minimum": 1 }, "updated_at": { "type": "string", "nullable": true }, "lines_count": { "type": "integer", "minimum": 1 }, "message": { "type": "string" } }, "type": "object" }, "TransformationLinesRequest": { "required": [ "lines", "version" ], "properties": { "lines": { "type": "array", "items": { "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "consumed_quantity": { "description": "Inputs only", "type": "string", "pattern": "^\\d{1,16}(?:\\.\\d{1,8})?$" }, "produced_quantity": { "description": "Outputs only", "type": "string", "pattern": "^\\d{1,16}(?:\\.\\d{1,8})?$" }, "unit_cost": { "description": "Accepted and ignored", "type": "string", "pattern": "^\\d{1,16}(?:\\.\\d{1,8})?$", "nullable": true, "deprecated": true }, "total_cost": { "description": "Accepted and ignored", "type": "string", "pattern": "^\\d{1,16}(?:\\.\\d{1,8})?$", "nullable": true, "deprecated": true } }, "type": "object" }, "minItems": 1 }, "version": { "type": "integer", "minimum": 1 } }, "type": "object" }, "TransformationLinesUpdated": { "required": [ "transformation_id", "lines_updated", "message" ], "properties": { "transformation_id": { "type": "string", "format": "uuid" }, "lines_updated": { "description": "Lines sent, changed or not; refetch the record for the new version", "type": "integer", "minimum": 1 }, "message": { "type": "string" } }, "type": "object" }, "TransformationStatusRequest": { "required": [ "status", "version" ], "properties": { "status": { "description": "en_proceso starts the process without checking stock; anulada releases nothing", "type": "string", "enum": [ "por_aprobar", "en_proceso", "procesada", "anulada" ] }, "version": { "type": "integer", "minimum": 1 } }, "type": "object" }, "TransformationProcessRequest": { "required": [ "version" ], "properties": { "version": { "type": "integer", "minimum": 1 } }, "type": "object" }, "TransformationProcessed": { "required": [ "id", "code", "status", "version", "processed_at", "processed_by", "message" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "status": { "type": "string", "enum": [ "procesada" ] }, "version": { "description": "Processing moves it by 2", "type": "integer", "minimum": 1 }, "processed_at": { "description": "UTC as Y-m-d H:i:s", "type": "string", "nullable": true }, "processed_by": { "type": "string", "nullable": true }, "message": { "type": "string" } }, "type": "object" }, "TransformationResponsibleRequest": { "required": [ "responsible_user_id" ], "properties": { "responsible_user_id": { "description": "A user of the transformation's company", "type": "integer", "minimum": 1 } }, "type": "object" }, "TransformationAcknowledgement": { "description": "Empty JSON object acknowledgement", "type": "object" }, "TransformationProblem": { "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "error_code": { "type": "string", "nullable": true }, "errors": { "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" }, "TransformationClosedProblem": { "description": "transformation_cannot_be_modified: the transformation is procesada or anulada and takes no further write", "required": [ "title", "status", "detail", "error_code", "errors", "transformation_status" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "error_code": { "type": "string", "enum": [ "transformation_cannot_be_modified" ] }, "errors": { "type": "object", "nullable": true }, "transformation_status": { "type": "string", "enum": [ "procesada", "anulada" ] } }, "type": "object" }, "TransformationCannotBeProcessedProblem": { "description": "transformation_cannot_be_processed: only an en_proceso transformation is processed", "required": [ "title", "status", "detail", "error_code", "errors", "transformation_status" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "error_code": { "type": "string", "enum": [ "transformation_cannot_be_processed" ] }, "errors": { "type": "object", "nullable": true }, "transformation_status": { "type": "string", "enum": [ "por_aprobar", "procesada", "anulada" ] } }, "type": "object" }, "TransformationInsufficientInventoryProblem": { "description": "insufficient_inventory: an input needs more than the transformation's input location holds; location_id is that input location", "required": [ "title", "status", "detail", "error_code", "errors", "item_id", "location_id", "available_quantity", "required_quantity" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "error_code": { "type": "string", "enum": [ "insufficient_inventory" ] }, "errors": { "type": "object", "nullable": true }, "item_id": { "type": "string", "format": "uuid" }, "location_id": { "type": "string", "format": "uuid" }, "available_quantity": { "type": "string", "example": "1.00000000", "nullable": true }, "required_quantity": { "type": "string", "example": "5.00000000", "nullable": true } }, "type": "object" }, "TransformationAccountingConfigurationError": { "required": [ "error", "missing" ], "properties": { "error": { "type": "string", "enum": [ "accounting_configuration_incomplete" ] }, "missing": { "type": "array", "items": { "required": [ "reason_code", "subject_type", "subject_id", "human_message", "details" ], "properties": { "reason_code": { "type": "string", "example": "PERIOD_CLOSED" }, "subject_type": { "type": "string" }, "subject_id": { "type": "string" }, "human_message": { "type": "string" }, "details": { "type": "array", "items": { "type": "string" } } }, "type": "object" } } }, "type": "object" }, "TransformationUnauthenticated": { "required": [ "message" ], "properties": { "message": { "type": "string" } }, "type": "object" }, "TransformationForbidden": { "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "error_code": { "type": "string", "nullable": true }, "errors": { "type": "object", "nullable": true } }, "type": "object" }, "VariantGroupCreateRequest": { "required": [ "id", "name", "option_names" ], "properties": { "id": { "description": "Client-supplied Modelo id.", "type": "string", "format": "uuid" }, "name": { "description": "1–120 characters after trimming, unique per company ignoring letter case (inactive Modelos included). A longer name answers 422 invalid_variant_group_name, up to the 1,000-character request cap, which answers request validation (error_code null); a taken one answers 409 variant_group_name_already_exists.", "type": "string", "maxLength": 1000 }, "option_names": { "description": "1 to 3 option names in display order, each 1–40 characters after trimming and distinct ignoring letter case. Otherwise 422 invalid_variant_group_option_count, invalid_variant_group_option_name or duplicate_variant_group_option_name; beyond the request caps (20 option names, 1,000 characters each) request validation answers instead (error_code null).", "type": "array", "items": { "type": "string", "maxLength": 1000 }, "maxItems": 20 } }, "type": "object" }, "VariantGroupUpdateRequest": { "description": "Replaces the name and the option names. Once the Modelo has Variantes its option names stay exactly as they are (order and letter case included) and any change answers 409 variant_group_options_locked; the name stays editable.", "required": [ "name", "option_names" ], "properties": { "name": { "description": "1–120 characters after trimming, unique per company ignoring letter case (inactive Modelos included). A longer name answers 422 invalid_variant_group_name, up to the 1,000-character request cap, which answers request validation (error_code null); a taken one answers 409 variant_group_name_already_exists.", "type": "string", "maxLength": 1000 }, "option_names": { "description": "1 to 3 option names in display order, each 1–40 characters after trimming and distinct ignoring letter case. Otherwise 422 invalid_variant_group_option_count, invalid_variant_group_option_name or duplicate_variant_group_option_name; beyond the request caps (20 option names, 1,000 characters each) request validation answers instead (error_code null).", "type": "array", "items": { "type": "string", "maxLength": 1000 }, "maxItems": 20 } }, "type": "object" }, "VariantGroup": { "required": [ "id", "name", "option_names", "status", "variants_count", "options_locked" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "example": "Polo" }, "option_names": { "description": "In display order.", "type": "array", "items": { "type": "string" }, "example": [ "Talla", "Color" ] }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "variants_count": { "description": "How many Variantes (Items) the Modelo has.", "type": "integer", "minimum": 0 }, "options_locked": { "description": "True when variants_count is above 0: the option names can no longer change.", "type": "boolean" } }, "type": "object" }, "VariantGroupDetail": { "description": "A Modelo's record: the Modelo as listed plus its Variantes. variants_count equals the number of variants; options_locked is true once any Item, in any status, belongs to it.", "required": [ "id", "name", "option_names", "status", "variants_count", "options_locked", "variants" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "example": "Polo" }, "option_names": { "description": "In display order.", "type": "array", "items": { "type": "string" }, "example": [ "Talla", "Color" ] }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "variants_count": { "description": "How many Variantes (Items, any status) the Modelo has: the length of variants.", "type": "integer", "minimum": 0 }, "options_locked": { "description": "True when variants_count is above 0: the option names can no longer change.", "type": "boolean" }, "variants": { "description": "Every Item of the Modelo, in any status, ordered by code then id ascending; unpaged. Empty when it has none.", "type": "array", "items": { "$ref": "#/components/schemas/VariantGroupVariant" } } }, "type": "object" }, "VariantGroupVariant": { "description": "One Variante of a Modelo: an Item with its value for each of the Modelo's options.", "required": [ "id", "code", "name", "sku", "barcode", "status", "variant_options" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string", "example": "ITM2600001" }, "name": { "type": "string", "example": "Polo M Rojo" }, "sku": { "type": "string", "nullable": true, "maxLength": 64 }, "barcode": { "type": "string", "nullable": true, "maxLength": 64 }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "variant_options": { "description": "In the Modelo's option order.", "type": "array", "items": { "$ref": "#/components/schemas/ItemVariantOption" } } }, "type": "object" }, "VariantGroupList": { "required": [ "items", "total", "per_page", "current_page", "meta" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/VariantGroup" } }, "total": { "type": "integer", "minimum": 0 }, "per_page": { "type": "integer", "minimum": 1 }, "current_page": { "type": "integer", "minimum": 1 }, "meta": { "required": [ "counts" ], "properties": { "counts": { "description": "Modelos per status under the company and the search, ignoring the status filter, the pagination and the sort.", "required": [ "active", "inactive" ], "properties": { "active": { "type": "integer", "minimum": 0 }, "inactive": { "type": "integer", "minimum": 0 } }, "type": "object" } }, "type": "object" } }, "type": "object" }, "VariantGroupProblem": { "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "error_code": { "description": "Null for request validation and authorization failures.", "type": "string", "nullable": true }, "errors": { "description": "Request validation messages by field, such as option_names.1.", "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" }, "VariantGroupMiddlewareNotFound": { "description": "Answered before the controller runs: by the router for an id that is not a UUID, by the tenancy middleware for an unknown company, or by the API key guardrails for a key bound to another company.", "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Recurso no encontrado" } }, "type": "object" }, "VariantGroupNotFound404": { "oneOf": [ { "$ref": "#/components/schemas/VariantGroupProblem" }, { "$ref": "#/components/schemas/VariantGroupMiddlewareNotFound" } ] }, "VariantGroupUnauthenticated": { "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" }, "PurchaseContractActivationItem": { "required": [ "id", "purchase_contract_item_id", "category_id", "item_id", "item_name", "quantity", "unit_id", "tariff_period", "unit_price", "tax_id", "tax_percentage", "discount_percentage", "accounting_center_id", "accounting_account_id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "purchase_contract_item_id": { "type": "string", "format": "uuid" }, "category_id": { "type": "string", "format": "uuid" }, "item_id": { "type": "string", "format": "uuid" }, "item_name": { "type": "string", "maxLength": 255 }, "quantity": { "type": "string", "pattern": "^\\d{1,11}(\\.\\d{1,4})?$", "example": "1.0000" }, "unit_id": { "type": "string", "format": "uuid" }, "tariff_period": { "type": "string", "enum": [ "semi_monthly", "monthly", "annually" ] }, "unit_price": { "description": "Read-only; inherited from the Purchase Contract line", "type": "string", "pattern": "^\\d{1,13}(\\.\\d{1,2})?$", "readOnly": true, "example": "100.00" }, "tax_id": { "type": "string", "format": "uuid" }, "tax_percentage": { "type": "string", "pattern": "^\\d{1,3}(\\.\\d{1,2})?$", "example": "18.00" }, "discount_percentage": { "type": "string", "pattern": "^\\d{1,3}(\\.\\d{1,2})?$", "example": "0.00" }, "accounting_center_id": { "type": "string", "format": "uuid" }, "accounting_account_id": { "type": "string", "format": "uuid" } }, "type": "object" }, "PurchaseContractActivationWriteRequest": { "required": [ "purchase_contract_id", "start_date", "due_date", "activation_date", "billing_start_date", "items" ], "properties": { "purchase_contract_id": { "type": "string", "format": "uuid" }, "start_date": { "type": "string", "format": "date" }, "due_date": { "type": "string", "format": "date" }, "activation_date": { "type": "string", "format": "date" }, "billing_start_date": { "type": "string", "format": "date" }, "observations": { "type": "string", "nullable": true, "maxLength": 16000 }, "items": { "type": "array", "items": { "required": [ "id", "purchase_contract_item_id", "category_id", "item_id", "item_name", "quantity", "unit_id", "tariff_period", "tax_id", "tax_percentage", "discount_percentage", "accounting_center_id", "accounting_account_id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "purchase_contract_item_id": { "type": "string", "format": "uuid" }, "category_id": { "type": "string", "format": "uuid" }, "item_id": { "type": "string", "format": "uuid" }, "item_name": { "type": "string", "maxLength": 255 }, "quantity": { "type": "string", "pattern": "^\\d{1,11}(\\.\\d{1,4})?$", "example": "1.0000" }, "unit_id": { "type": "string", "format": "uuid" }, "tariff_period": { "type": "string", "enum": [ "semi_monthly", "monthly", "annually" ] }, "tax_id": { "type": "string", "format": "uuid" }, "tax_percentage": { "type": "string", "pattern": "^\\d{1,3}(\\.\\d{1,2})?$", "example": "18.00" }, "discount_percentage": { "type": "string", "pattern": "^\\d{1,3}(\\.\\d{1,2})?$", "example": "0.00" }, "accounting_center_id": { "type": "string", "format": "uuid" }, "accounting_account_id": { "type": "string", "format": "uuid" } }, "type": "object" }, "minItems": 1 }, "preview": { "description": "Optional scale-2 preview. String amounts only. Null skips the comparison.", "properties": { "subtotal": { "type": "string", "pattern": "^\\d{1,13}(\\.\\d{1,2})?$" }, "discount": { "type": "string", "pattern": "^\\d{1,13}(\\.\\d{1,2})?$" }, "taxes": { "type": "string", "pattern": "^\\d{1,13}(\\.\\d{1,2})?$" }, "total": { "type": "string", "pattern": "^\\d{1,13}(\\.\\d{1,2})?$" }, "tax_groups": { "type": "array", "items": { "properties": { "tax_id": { "type": "string", "format": "uuid" }, "tax_percentage": { "type": "string", "pattern": "^\\d{1,3}(\\.\\d{1,2})?$" }, "base": { "type": "string", "pattern": "^\\d{1,13}(\\.\\d{1,2})?$" }, "tax": { "type": "string", "pattern": "^\\d{1,13}(\\.\\d{1,2})?$" } }, "type": "object" } } }, "type": "object", "nullable": true } }, "type": "object" }, "PurchaseContractActivationUpdateRequest": { "required": [ "start_date", "due_date", "activation_date", "billing_start_date", "items" ], "properties": { "start_date": { "type": "string", "format": "date" }, "due_date": { "type": "string", "format": "date" }, "activation_date": { "type": "string", "format": "date" }, "billing_start_date": { "type": "string", "format": "date" }, "observations": { "type": "string", "nullable": true, "maxLength": 16000 }, "items": { "type": "array", "items": { "required": [ "id", "purchase_contract_item_id", "category_id", "item_id", "item_name", "quantity", "unit_id", "tariff_period", "tax_id", "tax_percentage", "discount_percentage", "accounting_center_id", "accounting_account_id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "purchase_contract_item_id": { "type": "string", "format": "uuid" }, "category_id": { "type": "string", "format": "uuid" }, "item_id": { "type": "string", "format": "uuid" }, "item_name": { "type": "string", "maxLength": 255 }, "quantity": { "type": "string", "pattern": "^\\d{1,11}(\\.\\d{1,4})?$", "example": "1.0000" }, "unit_id": { "type": "string", "format": "uuid" }, "tariff_period": { "type": "string", "enum": [ "semi_monthly", "monthly", "annually" ] }, "tax_id": { "type": "string", "format": "uuid" }, "tax_percentage": { "type": "string", "pattern": "^\\d{1,3}(\\.\\d{1,2})?$", "example": "18.00" }, "discount_percentage": { "type": "string", "pattern": "^\\d{1,3}(\\.\\d{1,2})?$", "example": "0.00" }, "accounting_center_id": { "type": "string", "format": "uuid" }, "accounting_account_id": { "type": "string", "format": "uuid" } }, "type": "object" }, "minItems": 1 }, "preview": { "description": "Optional scale-2 preview. String amounts only. Null skips the comparison.", "required": [ "subtotal", "discount", "taxes", "total", "tax_groups" ], "properties": { "subtotal": { "type": "string", "pattern": "^\\d{1,13}(\\.\\d{1,2})?$" }, "discount": { "type": "string", "pattern": "^\\d{1,13}(\\.\\d{1,2})?$" }, "taxes": { "type": "string", "pattern": "^\\d{1,13}(\\.\\d{1,2})?$" }, "total": { "type": "string", "pattern": "^\\d{1,13}(\\.\\d{1,2})?$" }, "tax_groups": { "type": "array", "items": { "required": [ "tax_id", "tax_percentage", "base", "tax" ], "properties": { "tax_id": { "type": "string", "format": "uuid" }, "tax_percentage": { "type": "string", "pattern": "^\\d{1,3}(\\.\\d{1,2})?$" }, "base": { "type": "string", "pattern": "^\\d{1,13}(\\.\\d{1,2})?$" }, "tax": { "type": "string", "pattern": "^\\d{1,13}(\\.\\d{1,2})?$" } }, "type": "object" } } }, "type": "object", "nullable": true } }, "type": "object" }, "PurchaseContractActivationCreateRequest": { "allOf": [ { "$ref": "#/components/schemas/PurchaseContractActivationWriteRequest" }, { "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid" } }, "type": "object" } ] }, "PurchaseContractActivationResource": { "required": [ "id", "code", "purchase_contract_id", "provider_id", "start_date", "due_date", "activation_date", "billing_start_date", "status", "subtotal", "discount", "taxes", "total", "next_owed_date", "items", "purchase_contract_code", "provider_name", "purchase_contract_responsible_user_name", "pending_addendum", "pending_deactivation", "created_at", "updated_at", "labels" ], "properties": { "purchase_contract_code": { "type": "string", "nullable": true }, "provider_name": { "type": "string", "nullable": true }, "labels": { "type": "array", "items": { "$ref": "#/components/schemas/PurchaseContractActivationLabel" } }, "purchase_contract_responsible_user_name": { "type": "string", "nullable": true }, "pending_addendum": { "required": [ "id", "code" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" } }, "type": "object", "nullable": true }, "pending_deactivation": { "required": [ "id", "code" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" } }, "type": "object", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "nullable": true }, "updated_at": { "type": "string", "format": "date-time", "nullable": true }, "id": { "type": "string", "format": "uuid" }, "code": { "type": "string", "example": "PCA-00001" }, "purchase_contract_id": { "type": "string", "format": "uuid" }, "provider_id": { "type": "string", "format": "uuid" }, "start_date": { "type": "string", "format": "date" }, "due_date": { "type": "string", "format": "date" }, "activation_date": { "type": "string", "format": "date" }, "billing_start_date": { "type": "string", "format": "date" }, "status": { "type": "string", "enum": [ "to_approve", "active", "cancelled", "ended" ] }, "observations": { "type": "string", "nullable": true, "maxLength": 16000 }, "subtotal": { "type": "string", "pattern": "^\\d{1,13}\\.\\d{2}$", "example": "100.00" }, "discount": { "type": "string", "pattern": "^\\d{1,13}\\.\\d{2}$", "example": "0.00" }, "taxes": { "type": "string", "pattern": "^\\d{1,13}\\.\\d{2}$", "example": "18.00" }, "total": { "type": "string", "pattern": "^\\d{1,13}\\.\\d{2}$", "example": "118.00" }, "next_owed_date": { "description": "Earliest owed charge date strictly after today across all lines; null when none remain", "type": "string", "format": "date", "nullable": true }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/PurchaseContractActivationItem" } } }, "type": "object" }, "PurchaseContractActivationSummary": { "required": [ "id", "code", "purchase_contract_id", "provider_id", "start_date", "due_date", "total", "status", "activation_date", "billing_start_date", "purchase_contract_code", "provider_name", "labels" ], "properties": { "purchase_contract_code": { "type": "string", "nullable": true }, "provider_name": { "type": "string", "nullable": true }, "labels": { "type": "array", "items": { "$ref": "#/components/schemas/PurchaseContractActivationLabel" } }, "activation_date": { "type": "string", "format": "date" }, "billing_start_date": { "type": "string", "format": "date" }, "id": { "type": "string", "format": "uuid" }, "code": { "type": "string", "example": "PCA-00001" }, "purchase_contract_id": { "type": "string", "format": "uuid" }, "provider_id": { "type": "string", "format": "uuid" }, "start_date": { "type": "string", "format": "date" }, "due_date": { "type": "string", "format": "date" }, "total": { "type": "string", "pattern": "^\\d{1,13}\\.\\d{2}$", "example": "118.00" }, "status": { "type": "string", "enum": [ "to_approve", "active", "cancelled", "ended" ] } }, "type": "object" }, "PurchaseContractActivationMutationResponse": { "required": [ "id", "code", "status" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string", "example": "PCA-00001" }, "status": { "type": "string", "enum": [ "to_approve", "active", "cancelled", "ended" ] } }, "type": "object" }, "PurchaseContractActivationLifecycleResponse": { "required": [ "id", "status" ], "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "active", "cancelled", "ended" ] } }, "type": "object" }, "PurchaseContractActivationsPage": { "required": [ "items", "total", "per_page", "current_page", "meta" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/PurchaseContractActivationSummary" } }, "total": { "type": "integer", "minimum": 0 }, "per_page": { "type": "integer", "maximum": 100, "minimum": 1 }, "current_page": { "type": "integer", "minimum": 1 }, "meta": { "required": [ "counts", "label_counts" ], "properties": { "counts": { "required": [ "to_approve", "active", "cancelled", "ended" ], "properties": { "to_approve": { "type": "integer", "minimum": 0 }, "active": { "type": "integer", "minimum": 0 }, "cancelled": { "type": "integer", "minimum": 0 }, "ended": { "type": "integer", "minimum": 0 } }, "type": "object" }, "label_counts": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 0 } } }, "type": "object" } }, "type": "object" }, "PurchaseContractActivationProblem": { "required": [ "title", "status", "detail" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "error_code": { "type": "string", "nullable": true }, "errors": { "type": "object", "nullable": true } }, "type": "object" }, "PurchaseContractActivationLabel": { "required": [ "id", "name", "tone", "archived" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "tone": { "type": "string" }, "archived": { "type": "boolean" } }, "type": "object" }, "PurchaseContractActivationMiddlewareError": { "required": [ "message" ], "properties": { "message": { "type": "string" } }, "type": "object" }, "PurchaseContractActivationValidationError": { "required": [ "message", "errors" ], "properties": { "message": { "type": "string" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" }, "PurchaseContractAddendumItemWrite": { "required": [ "purchase_contract_activation_item_id", "action" ], "properties": { "purchase_contract_activation_item_id": { "type": "string", "format": "uuid" }, "action": { "type": "string", "enum": [ "keep", "change", "drop" ] }, "unit_price": { "description": "Required to differ for change; prohibited for keep/drop", "type": "string", "pattern": "^\\d+(\\.\\d{1,2})?$", "nullable": true }, "quantity": { "description": "Required to differ for change; prohibited for keep/drop", "type": "string", "pattern": "^\\d+(\\.\\d{1,4})?$", "nullable": true } }, "type": "object" }, "PurchaseContractAddendumItem": { "required": [ "id", "purchase_contract_activation_item_id", "purchase_contract_item_id", "action", "category_id", "item_id", "item_name", "quantity", "unit_id", "tariff_period", "unit_price", "tax_id", "tax_percentage", "discount_percentage", "accounting_center_id", "accounting_account_id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "purchase_contract_activation_item_id": { "type": "string", "format": "uuid" }, "purchase_contract_item_id": { "type": "string", "format": "uuid" }, "action": { "type": "string", "enum": [ "keep", "change", "drop" ] }, "category_id": { "type": "string", "format": "uuid" }, "item_id": { "type": "string", "format": "uuid" }, "item_name": { "type": "string" }, "quantity": { "type": "string", "example": "1.0000" }, "unit_id": { "type": "string", "format": "uuid" }, "tariff_period": { "type": "string", "enum": [ "semi_monthly", "monthly", "annually" ] }, "unit_price": { "type": "string", "example": "100.00" }, "tax_id": { "type": "string", "format": "uuid" }, "tax_percentage": { "type": "string", "example": "18.00" }, "discount_percentage": { "type": "string", "example": "0.00" }, "accounting_center_id": { "type": "string", "format": "uuid" }, "accounting_account_id": { "type": "string", "format": "uuid" }, "new_unit_price": { "type": "string", "nullable": true }, "new_quantity": { "type": "string", "nullable": true } }, "type": "object" }, "PurchaseContractAddendumUpdateRequest": { "required": [ "items" ], "properties": { "effective_date": { "description": "Optional; defaults to activation next_owed_date", "type": "string", "format": "date", "nullable": true }, "observations": { "type": "string", "nullable": true, "maxLength": 16000 }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/PurchaseContractAddendumItemWrite" } }, "preview": { "description": "Optional line-op preview. String amounts only. Null skips the comparison.", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/PurchaseContractAddendumPreview" } ] } }, "type": "object" }, "PurchaseContractAddendumPreviewLine": { "required": [ "purchase_contract_activation_item_id", "action", "quantity", "unit_price", "tax_id", "tax_percentage", "discount_percentage" ], "properties": { "purchase_contract_activation_item_id": { "type": "string", "format": "uuid" }, "action": { "type": "string", "enum": [ "keep", "change", "drop" ] }, "quantity": { "type": "string", "pattern": "^\\d+(\\.\\d{1,4})?$" }, "unit_price": { "type": "string", "pattern": "^\\d+(\\.\\d{1,2})?$" }, "tax_id": { "type": "string", "format": "uuid" }, "tax_percentage": { "type": "string", "pattern": "^(?:0*(?:[0-9]|[1-9][0-9])(?:\\.[0-9]{1,2})?|0*100(?:\\.0{1,2})?)$" }, "discount_percentage": { "type": "string", "pattern": "^(?:0*(?:[0-9]|[1-9][0-9])(?:\\.[0-9]{1,2})?|0*100(?:\\.0{1,2})?)$" }, "new_unit_price": { "type": "string", "pattern": "^\\d+(\\.\\d{1,2})?$", "nullable": true }, "new_quantity": { "type": "string", "pattern": "^\\d+(\\.\\d{1,4})?$", "nullable": true } }, "type": "object" }, "PurchaseContractAddendumPreview": { "required": [ "lines" ], "properties": { "lines": { "type": "array", "items": { "$ref": "#/components/schemas/PurchaseContractAddendumPreviewLine" } } }, "type": "object" }, "PurchaseContractAddendumCreateRequest": { "allOf": [ { "$ref": "#/components/schemas/PurchaseContractAddendumUpdateRequest" }, { "required": [ "id", "purchase_contract_activation_id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "purchase_contract_activation_id": { "type": "string", "format": "uuid" } }, "type": "object" } ] }, "PurchaseContractAddendumResource": { "required": [ "id", "code", "purchase_contract_id", "purchase_contract_activation_id", "provider_id", "effective_date", "status", "items", "purchase_contract_code", "purchase_contract_activation_code", "provider_name", "purchase_contract_responsible_user_name", "created_at", "updated_at", "labels", "approval_summary" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string", "example": "PCE2600001" }, "purchase_contract_id": { "type": "string", "format": "uuid" }, "purchase_contract_activation_id": { "type": "string", "format": "uuid" }, "provider_id": { "type": "string", "format": "uuid" }, "effective_date": { "type": "string", "format": "date" }, "status": { "type": "string", "enum": [ "to_approve", "approved", "cancelled" ] }, "purchase_contract_code": { "type": "string", "nullable": true }, "purchase_contract_activation_code": { "type": "string", "nullable": true }, "provider_name": { "type": "string", "nullable": true }, "labels": { "type": "array", "items": { "required": [ "id", "name", "tone", "archived" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "tone": { "type": "string" }, "archived": { "type": "boolean" } }, "type": "object" } }, "purchase_contract_responsible_user_name": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "nullable": true }, "updated_at": { "type": "string", "format": "date-time", "nullable": true }, "approval_summary": { "description": "Latest approval History counts; null when absent or malformed; independent of Activity pagination", "required": [ "charges_generated_count", "charges_invoiced_after_cutoff_count" ], "properties": { "charges_generated_count": { "type": "integer", "minimum": 0 }, "charges_invoiced_after_cutoff_count": { "type": "integer", "minimum": 0 } }, "type": "object", "nullable": true }, "observations": { "type": "string", "nullable": true }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/PurchaseContractAddendumItem" } } }, "type": "object" }, "PurchaseContractAddendumSummary": { "required": [ "id", "code", "purchase_contract_id", "purchase_contract_activation_id", "provider_id", "effective_date", "status", "purchase_contract_code", "purchase_contract_activation_code", "provider_name", "changed_lines", "dropped_lines", "labels" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string", "example": "PCE2600001" }, "purchase_contract_id": { "type": "string", "format": "uuid" }, "purchase_contract_activation_id": { "type": "string", "format": "uuid" }, "provider_id": { "type": "string", "format": "uuid" }, "effective_date": { "type": "string", "format": "date" }, "purchase_contract_code": { "type": "string", "nullable": true }, "purchase_contract_activation_code": { "type": "string", "nullable": true }, "provider_name": { "type": "string", "nullable": true }, "labels": { "type": "array", "items": { "required": [ "id", "name", "tone", "archived" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "tone": { "type": "string" }, "archived": { "type": "boolean" } }, "type": "object" } }, "changed_lines": { "type": "integer", "minimum": 0 }, "dropped_lines": { "type": "integer", "minimum": 0 }, "status": { "type": "string", "enum": [ "to_approve", "approved", "cancelled" ] } }, "type": "object" }, "PurchaseContractAddendumMutationResponse": { "required": [ "id", "code", "status" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string", "example": "PCE2600001" }, "status": { "type": "string", "enum": [ "to_approve", "approved", "cancelled" ] } }, "type": "object" }, "PurchaseContractAddendumApprovalResponse": { "required": [ "id", "status", "purchase_contract_id", "purchase_contract_activation_id", "effective_date", "charges_generated_count", "charges_invoiced_after_cutoff_count" ], "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "approved" ] }, "purchase_contract_id": { "type": "string", "format": "uuid" }, "purchase_contract_activation_id": { "description": "The Activation that remains active with rewritten lines", "type": "string", "format": "uuid" }, "effective_date": { "description": "First day charged under the new lines", "type": "string", "format": "date" }, "charges_generated_count": { "description": "Charges newly created under the old lines through the day before the effective date", "type": "integer", "minimum": 0 }, "charges_invoiced_after_cutoff_count": { "description": "Warning only: invoiced Charges dated on or after the effective date. Expected 0 under ADR 0110; may warn when invoiced post-cutoff rows exist", "type": "integer", "minimum": 0 } }, "type": "object" }, "PurchaseContractAddendaPage": { "required": [ "items", "total", "per_page", "current_page", "meta" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/PurchaseContractAddendumSummary" } }, "total": { "type": "integer" }, "per_page": { "type": "integer" }, "current_page": { "type": "integer" }, "meta": { "required": [ "counts", "label_counts" ], "properties": { "counts": { "description": "All filters except status", "required": [ "to_approve", "approved", "cancelled" ], "properties": { "to_approve": { "type": "integer", "minimum": 0 }, "approved": { "type": "integer", "minimum": 0 }, "cancelled": { "type": "integer", "minimum": 0 } }, "type": "object" }, "label_counts": { "description": "Distinct matching Addenda per active company label; all filters except label_ids; empty object when none", "type": "object", "additionalProperties": { "type": "integer", "minimum": 0 } } }, "type": "object" } }, "type": "object" }, "PurchaseContractAddendumMiddlewareError": { "required": [ "message" ], "properties": { "message": { "type": "string" } }, "type": "object" }, "PurchaseContractAddendumValidationError": { "required": [ "message", "errors" ], "properties": { "message": { "type": "string" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" }, "PurchaseContractAddendumDomainProblem": { "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "error_code": { "type": "string", "nullable": true }, "purchase_contract_activation_item_id": { "description": "Safe validated submitted row identity, when mappable", "type": "string", "format": "uuid" }, "errors": { "description": "Indexed submitted wire paths with Spanish field messages", "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" }, "PurchaseContractAddendumCommercialLine": { "required": [ "purchase_contract_activation_item_id", "action", "quantity", "unit_price", "discount_percentage", "tax_id", "tax_percentage", "new_quantity", "new_unit_price" ], "properties": { "purchase_contract_activation_item_id": { "type": "string", "format": "uuid" }, "action": { "type": "string", "enum": [ "keep", "change", "drop" ] }, "quantity": { "type": "string" }, "unit_price": { "type": "string" }, "discount_percentage": { "type": "string" }, "tax_id": { "type": "string", "format": "uuid" }, "tax_percentage": { "type": "string" }, "new_quantity": { "type": "string", "nullable": true }, "new_unit_price": { "type": "string", "nullable": true } }, "type": "object" }, "PurchaseContractAddendumHistoricalComparison": { "required": [ "error", "detail", "financial_fingerprint", "previous", "proposed" ], "properties": { "error": { "type": "string", "enum": [ "purchase_contract_addendum_historical_difference_acceptance_required", "purchase_contract_addendum_historical_difference_acceptance_stale" ] }, "detail": { "type": "string" }, "financial_fingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "previous": { "type": "array", "items": { "$ref": "#/components/schemas/PurchaseContractAddendumCommercialLine" } }, "proposed": { "type": "array", "items": { "$ref": "#/components/schemas/PurchaseContractAddendumCommercialLine" } } }, "type": "object" }, "PurchaseContractAddendumProblem": { "anyOf": [ { "$ref": "#/components/schemas/PurchaseContractAddendumDomainProblem" }, { "$ref": "#/components/schemas/PurchaseContractAddendumValidationError" }, { "$ref": "#/components/schemas/PurchaseContractAddendumMiddlewareError" }, { "$ref": "#/components/schemas/PurchaseContractAddendumHistoricalComparison" } ] }, "PurchaseContractAddendumSourceLine": { "required": [ "id", "item_name", "tariff_period", "unit_price", "quantity", "tax_id", "tax_percentage", "discount_percentage" ], "properties": { "id": { "type": "string", "format": "uuid" }, "item_name": { "type": "string" }, "tariff_period": { "type": "string" }, "unit_price": { "type": "string" }, "quantity": { "type": "string" }, "tax_id": { "type": "string", "format": "uuid" }, "tax_percentage": { "type": "string" }, "discount_percentage": { "type": "string" } }, "type": "object" }, "PurchaseContractAddendumSource": { "required": [ "id", "code", "purchase_contract_id", "purchase_contract_code", "provider_id", "provider_name", "status", "billing_start_date", "due_date", "next_owed_date", "items" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "purchase_contract_id": { "type": "string", "format": "uuid" }, "purchase_contract_code": { "type": "string" }, "provider_id": { "type": "string", "format": "uuid" }, "provider_name": { "type": "string", "nullable": true }, "status": { "type": "string" }, "billing_start_date": { "type": "string", "format": "date" }, "due_date": { "type": "string", "format": "date" }, "next_owed_date": { "type": "string", "format": "date", "nullable": true }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/PurchaseContractAddendumSourceLine" } } }, "type": "object" }, "PurchaseContractChargeSummary": { "required": [ "id", "code", "purchase_contract_id", "purchase_contract_activation_id", "provider_id", "item_name", "charge_date", "total", "status", "provider_name", "purchase_contract_code", "purchase_contract_activation_code", "purchases_invoice_code", "tariff_period", "purchases_invoice_id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string", "example": "PCC-00001" }, "purchase_contract_id": { "type": "string", "format": "uuid" }, "purchase_contract_activation_id": { "type": "string", "format": "uuid" }, "provider_id": { "type": "string", "format": "uuid" }, "item_name": { "type": "string", "maxLength": 255 }, "charge_date": { "type": "string", "format": "date" }, "total": { "description": "Persisted DECIMAL(15,2) numeric string; maximum 9999999999999.99", "type": "string", "pattern": "^\\d{1,13}\\.\\d{2}$", "example": "118.00" }, "status": { "type": "string", "enum": [ "to_be_invoiced", "invoiced", "cancelled" ] }, "provider_name": { "type": "string", "nullable": true }, "purchase_contract_code": { "type": "string", "nullable": true }, "purchase_contract_activation_code": { "type": "string", "nullable": true }, "purchases_invoice_code": { "type": "string", "nullable": true }, "tariff_period": { "type": "string", "enum": [ "semi_monthly", "monthly", "annually" ] }, "purchases_invoice_id": { "type": "string", "format": "uuid", "nullable": true } }, "type": "object" }, "PurchaseContractChargesPage": { "required": [ "items", "total", "per_page", "current_page", "meta" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/PurchaseContractChargeSummary" } }, "total": { "type": "integer", "minimum": 0 }, "per_page": { "type": "integer", "maximum": 100, "minimum": 1 }, "current_page": { "type": "integer", "minimum": 1 }, "meta": { "required": [ "counts" ], "properties": { "counts": { "required": [ "to_be_invoiced", "invoiced", "cancelled" ], "properties": { "to_be_invoiced": { "type": "integer", "minimum": 0 }, "invoiced": { "type": "integer", "minimum": 0 }, "cancelled": { "type": "integer", "minimum": 0 } }, "type": "object" } }, "type": "object" } }, "type": "object" }, "PurchaseContractChargeResource": { "required": [ "id", "code", "purchase_contract_id", "purchase_contract_activation_id", "purchase_contract_activation_item_id", "provider_id", "category_id", "item_id", "item_name", "quantity", "unit_id", "tariff_period", "unit_price", "tax_id", "tax_percentage", "discount_percentage", "subtotal", "discount", "taxes", "total", "charge_date", "status", "accounting_center_id", "accounting_account_id", "provider_name", "purchase_contract_code", "purchase_contract_activation_code", "purchases_invoice_code", "category_name", "unit_name", "tax_name", "accounting_center_name", "accounting_account_name", "created_at", "purchases_invoice_id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string", "example": "PCC-00001" }, "purchase_contract_id": { "type": "string", "format": "uuid" }, "purchase_contract_activation_id": { "type": "string", "format": "uuid" }, "purchase_contract_activation_item_id": { "type": "string", "format": "uuid" }, "provider_id": { "type": "string", "format": "uuid" }, "category_id": { "type": "string", "format": "uuid" }, "item_id": { "type": "string", "format": "uuid" }, "item_name": { "type": "string", "maxLength": 255 }, "quantity": { "type": "string", "pattern": "^\\d{1,11}(\\.\\d{1,4})?$", "example": "1.0000" }, "unit_id": { "type": "string", "format": "uuid" }, "tariff_period": { "type": "string", "enum": [ "semi_monthly", "monthly", "annually" ] }, "unit_price": { "type": "string", "pattern": "^\\d{1,13}(\\.\\d{1,2})?$", "example": "100.00" }, "tax_id": { "type": "string", "format": "uuid" }, "tax_percentage": { "type": "string", "pattern": "^\\d{1,3}(\\.\\d{1,2})?$", "example": "18.00" }, "discount_percentage": { "type": "string", "pattern": "^\\d{1,3}(\\.\\d{1,2})?$", "example": "0.00" }, "subtotal": { "description": "Persisted DECIMAL(15,2) numeric string; maximum 9999999999999.99", "type": "string", "pattern": "^\\d{1,13}\\.\\d{2}$", "example": "100.00" }, "discount": { "description": "Persisted DECIMAL(15,2) numeric string; maximum 9999999999999.99", "type": "string", "pattern": "^\\d{1,13}\\.\\d{2}$", "example": "0.00" }, "taxes": { "description": "Persisted DECIMAL(15,2) numeric string; maximum 9999999999999.99", "type": "string", "pattern": "^\\d{1,13}\\.\\d{2}$", "example": "18.00" }, "total": { "description": "Persisted DECIMAL(15,2) numeric string; maximum 9999999999999.99", "type": "string", "pattern": "^\\d{1,13}\\.\\d{2}$", "example": "118.00" }, "charge_date": { "type": "string", "format": "date" }, "status": { "type": "string", "enum": [ "to_be_invoiced", "invoiced", "cancelled" ] }, "accounting_center_id": { "type": "string", "format": "uuid" }, "accounting_account_id": { "type": "string", "format": "uuid" }, "purchases_invoice_id": { "type": "string", "format": "uuid", "nullable": true }, "provider_name": { "type": "string", "nullable": true }, "purchase_contract_code": { "type": "string", "nullable": true }, "purchase_contract_activation_code": { "type": "string", "nullable": true }, "purchases_invoice_code": { "type": "string", "nullable": true }, "category_name": { "type": "string", "nullable": true }, "unit_name": { "type": "string", "nullable": true }, "tax_name": { "type": "string", "nullable": true }, "accounting_center_name": { "type": "string", "nullable": true }, "accounting_account_name": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "nullable": true } }, "type": "object" }, "PurchaseContractChargeProblem": { "required": [ "title", "status", "detail" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "error_code": { "description": "Stable domain code, e.g. purchase_contract_charge_not_found.", "type": "string", "nullable": true }, "errors": { "type": "object", "nullable": true } }, "type": "object" }, "PurchaseContractChargeValidationProblem": { "required": [ "message", "errors" ], "properties": { "message": { "type": "string" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" }, "PurchaseContractChargeMessageProblem": { "required": [ "message" ], "properties": { "message": { "type": "string" } }, "type": "object" }, "PurchaseContractDeactivationItem": { "required": [ "id", "purchase_contract_activation_item_id", "purchase_contract_item_id", "category_id", "item_id", "item_name", "quantity", "unit_id", "tariff_period", "unit_price", "tax_id", "tax_percentage", "discount_percentage", "accounting_center_id", "accounting_account_id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "purchase_contract_activation_item_id": { "description": "The Activation line this snapshot was copied from", "type": "string", "format": "uuid" }, "purchase_contract_item_id": { "type": "string", "format": "uuid" }, "category_id": { "type": "string", "format": "uuid" }, "item_id": { "type": "string", "format": "uuid" }, "item_name": { "type": "string", "maxLength": 255 }, "quantity": { "type": "string", "pattern": "^\\d{1,11}(\\.\\d{1,4})?$", "example": "1.0000" }, "unit_id": { "type": "string", "format": "uuid" }, "tariff_period": { "type": "string", "enum": [ "semi_monthly", "monthly", "annually" ] }, "unit_price": { "type": "string", "pattern": "^\\d{1,13}(\\.\\d{1,2})?$", "example": "100.00" }, "tax_id": { "type": "string", "format": "uuid" }, "tax_percentage": { "type": "string", "pattern": "^\\d{1,3}(\\.\\d{1,2})?$", "example": "18.00" }, "discount_percentage": { "type": "string", "pattern": "^\\d{1,3}(\\.\\d{1,2})?$", "example": "0.00" }, "accounting_center_id": { "type": "string", "format": "uuid" }, "accounting_account_id": { "type": "string", "format": "uuid" } }, "type": "object" }, "PurchaseContractDeactivationUpdateRequest": { "required": [ "effective_deactivation_date" ], "properties": { "effective_deactivation_date": { "description": "Inclusive last chargeable day; must be on or after the Activation billing start date", "type": "string", "format": "date" }, "observations": { "type": "string", "nullable": true, "maxLength": 16000 } }, "type": "object" }, "PurchaseContractDeactivationCreateRequest": { "allOf": [ { "$ref": "#/components/schemas/PurchaseContractDeactivationUpdateRequest" }, { "required": [ "id", "purchase_contract_activation_id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "purchase_contract_activation_id": { "description": "The active Activation being deactivated; its lines are snapshotted server-side and may never be supplied by the client", "type": "string", "format": "uuid" } }, "type": "object" } ] }, "PurchaseContractDeactivationResource": { "required": [ "id", "code", "purchase_contract_id", "purchase_contract_activation_id", "provider_id", "effective_deactivation_date", "status", "subtotal", "discount", "taxes", "total", "items", "provider_name", "purchase_contract_code", "purchase_contract_activation_code", "purchase_contract_responsible_user_name", "billing_start_date", "created_at", "updated_at", "labels", "approval_summary", "approval_activity" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string", "example": "PCD-00001" }, "purchase_contract_id": { "type": "string", "format": "uuid" }, "purchase_contract_activation_id": { "type": "string", "format": "uuid" }, "provider_id": { "type": "string", "format": "uuid" }, "effective_deactivation_date": { "type": "string", "format": "date" }, "status": { "type": "string", "enum": [ "to_approve", "approved", "cancelled" ] }, "observations": { "type": "string", "nullable": true, "maxLength": 16000 }, "subtotal": { "type": "string", "pattern": "^\\d{1,13}\\.\\d{2}$", "example": "100.00" }, "discount": { "type": "string", "pattern": "^\\d{1,13}\\.\\d{2}$", "example": "0.00" }, "taxes": { "type": "string", "pattern": "^\\d{1,13}\\.\\d{2}$", "example": "18.00" }, "total": { "type": "string", "pattern": "^\\d{1,13}\\.\\d{2}$", "example": "118.00" }, "provider_name": { "type": "string", "nullable": true }, "purchase_contract_code": { "type": "string", "nullable": true }, "purchase_contract_activation_code": { "type": "string", "nullable": true }, "purchase_contract_responsible_user_name": { "type": "string", "nullable": true }, "billing_start_date": { "type": "string", "format": "date", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "nullable": true }, "updated_at": { "type": "string", "format": "date-time", "nullable": true }, "approval_summary": { "description": "Unavailable is null; zero counts are a valid captured approval", "required": [ "charges_generated_count", "charges_cancelled_count", "charges_invoiced_after_cutoff_count" ], "properties": { "charges_generated_count": { "type": "integer", "minimum": 0 }, "charges_cancelled_count": { "type": "integer", "minimum": 0 }, "charges_invoiced_after_cutoff_count": { "type": "integer", "minimum": 0 } }, "type": "object", "nullable": true }, "approval_activity": { "description": "The same latest valid captured approval as approval_summary, independent of History paging", "required": [ "history_id", "event", "code", "created_at", "user_id", "actor_name", "purchase_contract_id", "purchase_contract_code", "purchase_contract_activation_id", "purchase_contract_activation_code", "effective_deactivation_date", "charges_generated_count", "charges_cancelled_count", "charges_invoiced_after_cutoff_count" ], "properties": { "history_id": { "type": "string", "format": "uuid" }, "event": { "type": "string", "enum": [ "approved" ] }, "code": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "user_id": { "type": "string" }, "actor_name": { "type": "string" }, "purchase_contract_id": { "type": "string", "format": "uuid" }, "purchase_contract_code": { "type": "string", "nullable": true }, "purchase_contract_activation_id": { "type": "string", "format": "uuid" }, "purchase_contract_activation_code": { "type": "string", "nullable": true }, "effective_deactivation_date": { "type": "string", "format": "date" }, "charges_generated_count": { "type": "integer", "minimum": 0 }, "charges_cancelled_count": { "type": "integer", "minimum": 0 }, "charges_invoiced_after_cutoff_count": { "type": "integer", "minimum": 0 } }, "type": "object", "nullable": true }, "labels": { "type": "array", "items": { "required": [ "id", "name", "tone", "archived" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "tone": { "type": "string" }, "archived": { "type": "boolean" } }, "type": "object" } }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/PurchaseContractDeactivationItem" } } }, "type": "object" }, "PurchaseContractDeactivationSummary": { "required": [ "id", "code", "purchase_contract_id", "purchase_contract_activation_id", "provider_id", "effective_deactivation_date", "total", "status", "provider_name", "purchase_contract_code", "purchase_contract_activation_code", "labels" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string", "example": "PCD-00001" }, "purchase_contract_id": { "type": "string", "format": "uuid" }, "purchase_contract_activation_id": { "type": "string", "format": "uuid" }, "provider_id": { "type": "string", "format": "uuid" }, "effective_deactivation_date": { "type": "string", "format": "date" }, "total": { "type": "string", "pattern": "^\\d{1,13}\\.\\d{2}$", "example": "118.00" }, "status": { "type": "string", "enum": [ "to_approve", "approved", "cancelled" ] }, "provider_name": { "type": "string", "nullable": true }, "purchase_contract_code": { "type": "string", "nullable": true }, "purchase_contract_activation_code": { "type": "string", "nullable": true }, "labels": { "type": "array", "items": { "required": [ "id", "name", "tone", "archived" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "tone": { "type": "string" }, "archived": { "type": "boolean" } }, "type": "object" } } }, "type": "object" }, "PurchaseContractDeactivationMutationResponse": { "required": [ "id", "code", "status" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string", "example": "PCD-00001" }, "status": { "type": "string", "enum": [ "to_approve", "approved", "cancelled" ] } }, "type": "object" }, "PurchaseContractDeactivationApprovalResponse": { "required": [ "id", "status", "purchase_contract_id", "purchase_contract_activation_id", "effective_deactivation_date", "charges_generated_count", "charges_cancelled_count", "charges_invoiced_after_cutoff_count" ], "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "approved" ] }, "purchase_contract_id": { "type": "string", "format": "uuid" }, "purchase_contract_activation_id": { "description": "The Activation now ended", "type": "string", "format": "uuid" }, "effective_deactivation_date": { "description": "The inclusive cutoff actually applied", "type": "string", "format": "date" }, "charges_generated_count": { "description": "Charges newly created by this approval; already-existing owed Charges are not counted", "type": "integer", "minimum": 0 }, "charges_cancelled_count": { "description": "Open to_be_invoiced Charges of this Activation dated strictly after the cutoff, moved to cancelled", "type": "integer", "minimum": 0 }, "charges_invoiced_after_cutoff_count": { "description": "Warning only: invoiced Charges dated strictly after the cutoff. Nothing is mutated; correct them by cancelling the Purchases Invoice", "type": "integer", "minimum": 0 } }, "type": "object" }, "PurchaseContractDeactivationsPage": { "required": [ "items", "total", "per_page", "current_page", "meta" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/PurchaseContractDeactivationSummary" } }, "total": { "type": "integer", "minimum": 0 }, "per_page": { "type": "integer", "maximum": 100, "minimum": 1 }, "current_page": { "type": "integer", "minimum": 1 }, "meta": { "required": [ "counts", "label_counts" ], "properties": { "counts": { "required": [ "to_approve", "approved", "cancelled" ], "properties": { "to_approve": { "type": "integer", "minimum": 0 }, "approved": { "type": "integer", "minimum": 0 }, "cancelled": { "type": "integer", "minimum": 0 } }, "type": "object" }, "label_counts": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 0 } } }, "type": "object" } }, "type": "object" }, "PurchaseContractDeactivationProblem": { "required": [ "title", "status", "detail" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "error_code": { "type": "string", "nullable": true }, "errors": { "type": "object", "nullable": true } }, "type": "object" }, "PurchaseContractDeactivationApprovalSummary": { "required": [ "charges_generated_count", "charges_cancelled_count", "charges_invoiced_after_cutoff_count" ], "properties": { "charges_generated_count": { "type": "integer", "minimum": 0 }, "charges_cancelled_count": { "type": "integer", "minimum": 0 }, "charges_invoiced_after_cutoff_count": { "type": "integer", "minimum": 0 } }, "type": "object" }, "PurchaseContractDeactivationApprovalActivity": { "allOf": [ { "$ref": "#/components/schemas/PurchaseContractDeactivationApprovalSummary" }, { "required": [ "history_id", "event", "code", "created_at", "user_id", "actor_name", "purchase_contract_id", "purchase_contract_code", "purchase_contract_activation_id", "purchase_contract_activation_code", "effective_deactivation_date" ], "properties": { "history_id": { "type": "string", "format": "uuid" }, "event": { "type": "string", "enum": [ "approved" ] }, "code": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "user_id": { "type": "string" }, "actor_name": { "type": "string" }, "purchase_contract_id": { "type": "string", "format": "uuid" }, "purchase_contract_code": { "type": "string", "nullable": true }, "purchase_contract_activation_id": { "type": "string", "format": "uuid" }, "purchase_contract_activation_code": { "type": "string", "nullable": true }, "effective_deactivation_date": { "type": "string", "format": "date" } }, "type": "object" } ] }, "PurchaseContractDeactivationAmounts": { "required": [ "subtotal", "discount", "taxes", "total" ], "properties": { "subtotal": { "type": "string" }, "discount": { "type": "string" }, "taxes": { "type": "string" }, "total": { "type": "string" } }, "type": "object" }, "PurchaseContractDeactivationHistoricalDifferenceProblem": { "required": [ "error", "detail", "financial_fingerprint", "previous", "proposed" ], "properties": { "error": { "type": "string", "enum": [ "purchase_contract_deactivation_historical_difference_acceptance_required", "purchase_contract_deactivation_historical_difference_acceptance_stale" ] }, "detail": { "type": "string" }, "financial_fingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "previous": { "$ref": "#/components/schemas/PurchaseContractDeactivationAmounts" }, "proposed": { "$ref": "#/components/schemas/PurchaseContractDeactivationAmounts" } }, "type": "object" }, "PurchaseContractDeactivationValidationProblem": { "required": [ "message", "errors" ], "properties": { "message": { "type": "string" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" }, "PurchaseContractDeactivationSourceContract": { "required": [ "id", "code", "provider_id", "provider_name", "responsible_user_name", "status", "start_date", "due_date" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "provider_id": { "type": "string", "format": "uuid" }, "provider_name": { "type": "string", "nullable": true }, "responsible_user_name": { "type": "string", "nullable": true }, "status": { "type": "string" }, "start_date": { "type": "string", "format": "date" }, "due_date": { "type": "string", "format": "date" } }, "type": "object" }, "PurchaseContractDeactivationSourceActivation": { "required": [ "id", "code", "purchase_contract_id", "provider_id", "provider_name", "status", "start_date", "due_date", "activation_date", "billing_start_date", "subtotal", "discount", "taxes", "total", "items" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "purchase_contract_id": { "type": "string", "format": "uuid" }, "provider_id": { "type": "string", "format": "uuid" }, "provider_name": { "type": "string", "nullable": true }, "status": { "type": "string" }, "start_date": { "type": "string", "format": "date" }, "due_date": { "type": "string", "format": "date" }, "activation_date": { "type": "string", "format": "date" }, "billing_start_date": { "type": "string", "format": "date" }, "subtotal": { "type": "string" }, "discount": { "type": "string" }, "taxes": { "type": "string" }, "total": { "type": "string" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/PurchaseContractActivationItem" } } }, "type": "object" }, "PurchaseContractDeactivationSource": { "required": [ "contract", "activation", "pending_addendum", "pending_deactivation" ], "properties": { "contract": { "$ref": "#/components/schemas/PurchaseContractDeactivationSourceContract" }, "activation": { "$ref": "#/components/schemas/PurchaseContractDeactivationSourceActivation" }, "pending_addendum": { "required": [ "id", "code" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" } }, "type": "object", "nullable": true }, "pending_deactivation": { "required": [ "id", "code" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" } }, "type": "object", "nullable": true } }, "type": "object" }, "PurchaseContractItem": { "required": [ "id", "category_id", "item_id", "item_name", "quantity", "unit_id", "tariff_period", "unit_price", "tax_id", "tax_percentage", "discount_percentage", "accounting_center_id", "accounting_account_id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "category_id": { "type": "string", "format": "uuid" }, "item_id": { "type": "string", "format": "uuid" }, "item_name": { "type": "string", "maxLength": 255 }, "quantity": { "type": "string", "pattern": "^\\d{1,11}(\\.\\d{1,4})?$", "example": "1.0000" }, "unit_id": { "type": "string", "format": "uuid" }, "tariff_period": { "type": "string", "enum": [ "semi_monthly", "monthly", "annually" ] }, "unit_price": { "type": "string", "pattern": "^\\d{1,13}(\\.\\d{1,2})?$", "example": "100.00" }, "tax_id": { "type": "string", "format": "uuid" }, "tax_percentage": { "type": "string", "pattern": "^\\d{1,3}(\\.\\d{1,2})?$", "example": "18.00" }, "discount_percentage": { "type": "string", "pattern": "^\\d{1,3}(\\.\\d{1,2})?$", "example": "0.00" }, "accounting_center_id": { "type": "string", "format": "uuid" }, "accounting_account_id": { "type": "string", "format": "uuid" } }, "type": "object" }, "PurchaseContractWriteRequest": { "required": [ "provider_id", "start_date", "due_date", "recurring_billing", "accounting_center_id", "payment_term", "accounting_account_payable_id", "items" ], "properties": { "provider_id": { "type": "string", "format": "uuid" }, "start_date": { "type": "string", "format": "date" }, "due_date": { "type": "string", "format": "date" }, "recurring_billing": { "type": "string", "enum": [ "daily", "semi_monthly", "monthly", "annually" ] }, "accounting_center_id": { "type": "string", "format": "uuid" }, "payment_term": { "type": "string", "enum": [ "cash", "five_days", "seven_days", "fifteen_days", "thirty_days" ] }, "accounting_account_payable_id": { "type": "string", "format": "uuid" }, "location_id": { "type": "string", "format": "uuid", "nullable": true }, "reference": { "type": "string", "nullable": true, "maxLength": 255 }, "observations": { "type": "string", "nullable": true, "maxLength": 16000 }, "generated_invoice_final_status": { "description": "Defaults to to_be_approved when omitted.", "type": "string", "nullable": true, "enum": [ "to_be_approved", "approved" ] }, "generated_payment_final_status": { "description": "Defaults to none when omitted. Anything other than none requires generated_invoice_final_status=approved plus payment_instrument_id.", "type": "string", "nullable": true, "enum": [ "none", "to_be_approved", "to_be_applied", "applied" ] }, "payment_instrument_id": { "description": "The Company's Payment Instrument the generated Payment goes through, active or not: an inactive one is the documented degrade path (the payment stops at approval), not a write error. Another company's or an unknown instrument answers 404 purchase_contract_payment_instrument_not_found.", "type": "string", "format": "uuid", "nullable": true }, "payment_method_reference_email": { "description": "Binance Pay payout email; while generated_payment_final_status is not none, only with a crypto_wallet instrument (422 purchase_contract_method_reference_requires_crypto_wallet). Falls back to the provider's own payment reference when omitted.", "type": "string", "format": "email", "nullable": true, "maxLength": 255 }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/PurchaseContractItem" }, "minItems": 1 }, "preview": { "description": "Optional scale-2 preview. String amounts only. Null skips the comparison.", "properties": { "subtotal": { "type": "string", "pattern": "^\\d{1,13}(\\.\\d{1,2})?$" }, "discount": { "type": "string", "pattern": "^\\d{1,13}(\\.\\d{1,2})?$" }, "taxes": { "type": "string", "pattern": "^\\d{1,13}(\\.\\d{1,2})?$" }, "total": { "type": "string", "pattern": "^\\d{1,13}(\\.\\d{1,2})?$" }, "tax_groups": { "type": "array", "items": { "properties": { "tax_id": { "type": "string", "format": "uuid" }, "tax_percentage": { "type": "string", "pattern": "^\\d{1,3}(\\.\\d{1,2})?$" }, "base": { "type": "string", "pattern": "^\\d{1,13}(\\.\\d{1,2})?$" }, "tax": { "type": "string", "pattern": "^\\d{1,13}(\\.\\d{1,2})?$" } }, "type": "object" } } }, "type": "object", "nullable": true } }, "type": "object" }, "PurchaseContractCreateRequest": { "allOf": [ { "$ref": "#/components/schemas/PurchaseContractWriteRequest" }, { "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "responsible_user_id": { "description": "Optional company member; omission initializes unassigned", "type": "string", "nullable": true } }, "type": "object" } ] }, "PurchaseContractResource": { "required": [ "id", "code", "provider_id", "start_date", "due_date", "recurring_billing", "accounting_center_id", "payment_term", "accounting_account_payable_id", "status", "subtotal", "discount", "taxes", "total", "items", "payment_instrument_id", "payment_instrument" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string", "example": "PCT-00001" }, "provider_name": { "type": "string", "nullable": true }, "responsible_user_id": { "type": "string", "nullable": true }, "responsible_user_name": { "type": "string", "nullable": true }, "labels": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "tone": { "type": "string" }, "archived": { "type": "boolean" } }, "type": "object" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "active_activation": { "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" } }, "type": "object", "nullable": true }, "automation_blocked": { "type": "boolean" }, "automation_block_reasons": { "type": "array", "items": { "type": "string" } }, "automation_block_stages": { "type": "array", "items": { "type": "string" } }, "provider_id": { "type": "string", "format": "uuid" }, "start_date": { "type": "string", "format": "date" }, "due_date": { "type": "string", "format": "date" }, "recurring_billing": { "type": "string", "enum": [ "daily", "semi_monthly", "monthly", "annually" ] }, "accounting_center_id": { "type": "string", "format": "uuid" }, "payment_term": { "type": "string", "enum": [ "cash", "five_days", "seven_days", "fifteen_days", "thirty_days" ] }, "accounting_account_payable_id": { "type": "string", "format": "uuid" }, "location_id": { "type": "string", "format": "uuid", "nullable": true }, "status": { "type": "string", "enum": [ "pending_approval", "active", "cancelled" ] }, "reference": { "type": "string", "nullable": true }, "observations": { "type": "string", "nullable": true, "maxLength": 16000 }, "generated_invoice_final_status": { "type": "string", "enum": [ "to_be_approved", "approved" ] }, "generated_payment_final_status": { "type": "string", "enum": [ "none", "to_be_approved", "to_be_applied", "applied" ] }, "payment_instrument_id": { "type": "string", "format": "uuid", "nullable": true }, "payment_instrument": { "description": "The stored instrument whatever its status, since the instrument lookup lists active ones only. Null when the contract names none.", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/PurchaseContractPaymentInstrument" } ] }, "payment_method_reference_email": { "type": "string", "format": "email", "nullable": true }, "subtotal": { "description": "Persisted DECIMAL(15,2) numeric string; maximum 9999999999999.99", "type": "string", "pattern": "^\\d{1,13}\\.\\d{2}$", "example": "100.00" }, "discount": { "description": "Persisted DECIMAL(15,2) numeric string; maximum 9999999999999.99", "type": "string", "pattern": "^\\d{1,13}\\.\\d{2}$", "example": "0.00" }, "taxes": { "description": "Persisted DECIMAL(15,2) numeric string; maximum 9999999999999.99", "type": "string", "pattern": "^\\d{1,13}\\.\\d{2}$", "example": "18.00" }, "total": { "description": "Persisted DECIMAL(15,2) numeric string; maximum 9999999999999.99", "type": "string", "pattern": "^\\d{1,13}\\.\\d{2}$", "example": "118.00" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/PurchaseContractItem" } } }, "type": "object" }, "PurchaseContractSummary": { "required": [ "id", "code", "provider_id", "start_date", "due_date", "total", "status", "automation_blocked", "automation_block_reasons", "automation_block_stages" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string", "example": "PCT-00001" }, "provider_name": { "type": "string", "nullable": true }, "responsible_user_id": { "type": "string", "nullable": true }, "responsible_user_name": { "type": "string", "nullable": true }, "labels": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "tone": { "type": "string" }, "archived": { "type": "boolean" } }, "type": "object" } }, "reference": { "type": "string", "nullable": true }, "recurring_billing": { "type": "string", "enum": [ "daily", "semi_monthly", "monthly", "annually" ] }, "provider_id": { "type": "string", "format": "uuid" }, "start_date": { "type": "string", "format": "date" }, "due_date": { "type": "string", "format": "date" }, "total": { "description": "Persisted DECIMAL(15,2) numeric string; maximum 9999999999999.99", "type": "string", "pattern": "^\\d{1,13}\\.\\d{2}$", "example": "118.00" }, "status": { "type": "string", "enum": [ "pending_approval", "active", "cancelled" ] }, "automation_blocked": { "description": "True while an unresolved automation block row exists for this contract at ANY stage.", "type": "boolean" }, "automation_block_reasons": { "description": "Reason codes merged across every blocked stage and period; never includes the internal detail text. Payment-stage codes are `CONTRACT_NOT_ACTIVE`, `PAYMENT_CURRENCY_PAIR_NOT_SUPPORTED`, `PROVIDER_SETTLEMENT_TERMS_MISSING`, `PAYMENT_INSTRUMENT_NOT_USABLE`, `PAYMENT_BALANCE_TOO_SMALL_TO_CONVERT`, `UNEXPECTED_FAILURE`, plus any accounting readiness reason passed through verbatim (e.g. `CASH_BANK_ACCOUNT_MISSING`, `OFFICIAL_RATE_STALE`, `OFFICIAL_RATE_NOT_AVAILABLE`, `EXCHANGE_POSTING_ACCOUNT_MISSING`). Older rows may still read `INVOICE_CURRENCY_DIFFERS_FROM_INSTRUMENT` or `INVOICE_CURRENCY_NOT_SUPPORTED`. Open set: clients fall back to the raw code.", "type": "array", "items": { "type": "string" } }, "automation_block_stages": { "description": "Which automation stages are currently blocked.", "type": "array", "items": { "type": "string", "enum": [ "charge_generation", "invoicing", "invoice_approval", "payment" ] } } }, "type": "object" }, "PurchaseContractAutomationLevelRequest": { "required": [ "generated_invoice_final_status", "generated_payment_final_status" ], "properties": { "generated_invoice_final_status": { "type": "string", "enum": [ "to_be_approved", "approved" ] }, "generated_payment_final_status": { "type": "string", "enum": [ "none", "to_be_approved", "to_be_applied", "applied" ] }, "payment_instrument_id": { "description": "Required by the domain when generated_payment_final_status is not none. Another company's or an unknown instrument answers 404 purchase_contract_payment_instrument_not_found.", "type": "string", "format": "uuid", "nullable": true }, "payment_method_reference_email": { "description": "Binance Pay payout email; while generated_payment_final_status is not none, only with a crypto_wallet instrument.", "type": "string", "format": "email", "nullable": true, "maxLength": 255 } }, "type": "object" }, "PurchaseContractAutomationLevelResponse": { "required": [ "id", "status", "generated_invoice_final_status", "generated_payment_final_status", "payment_instrument_id", "payment_method_reference_email" ], "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "pending_approval", "active" ] }, "generated_invoice_final_status": { "type": "string", "enum": [ "to_be_approved", "approved" ] }, "generated_payment_final_status": { "type": "string", "enum": [ "none", "to_be_approved", "to_be_applied", "applied" ] }, "payment_instrument_id": { "type": "string", "format": "uuid", "nullable": true }, "payment_method_reference_email": { "type": "string", "format": "email", "nullable": true } }, "type": "object" }, "PurchaseContractPaymentInstrument": { "required": [ "id", "name", "class", "status", "currency" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "class": { "type": "string", "enum": [ "cash", "bank_transfer", "mobile_payment", "point_of_sale", "zelle", "crypto_wallet", "check", "card" ] }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "currency": { "description": "The instrument's Treasury currency.", "type": "string", "example": "USD", "enum": [ "USD", "VES", "USDT", "EUR", "DOP" ] } }, "type": "object" }, "PurchaseContractMutationResponse": { "required": [ "id", "code", "status" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string", "example": "PCT-00001" }, "status": { "type": "string", "enum": [ "pending_approval", "active", "cancelled" ] } }, "type": "object" }, "PurchaseContractStatusResponse": { "required": [ "id", "status" ], "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "active", "cancelled" ] } }, "type": "object" }, "PurchaseContractsPage": { "required": [ "items", "total", "per_page", "current_page" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/PurchaseContractSummary" } }, "total": { "type": "integer", "minimum": 0 }, "per_page": { "type": "integer", "maximum": 100, "minimum": 1 }, "current_page": { "type": "integer", "minimum": 1 }, "meta": { "properties": { "counts": { "properties": { "pending_approval": { "type": "integer" }, "active": { "type": "integer" }, "cancelled": { "type": "integer" } }, "type": "object" }, "label_counts": { "type": "object", "additionalProperties": { "type": "integer" } } }, "type": "object" } }, "type": "object" }, "PurchaseContractProblem": { "required": [ "title", "status", "detail" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "error_code": { "description": "Stable domain code. Financial bounds use purchase_contract_calculated_total_exceeds_storage_limit or purchase_contract_observations_too_long; automation writes use invalid_purchase_contract_automation_level, incomplete_purchase_contract_payment_defaults, purchase_contract_payment_instrument_not_found, purchase_contract_method_reference_requires_crypto_wallet or purchase_contract_cannot_change_automation. Lines their item refuses use purchase_line_item_mismatch, whose errors names each refused line field (items.N.category_id, items.N.unit_id).", "type": "string", "nullable": true }, "errors": { "type": "object", "nullable": true } }, "type": "object" }, "PurchaseContractMiddlewareError": { "required": [ "message" ], "properties": { "message": { "type": "string" } }, "type": "object" }, "PurchaseContractValidationError": { "required": [ "message", "errors" ], "properties": { "message": { "type": "string" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" }, "SupplierCreditApplicationProblem": { "description": "Controller validation and domain errors. Validation has a null error_code and an errors object mapping field names to messages; domain refusals have an error_code and null errors.", "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "error_code": { "type": "string", "nullable": true }, "errors": { "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" }, "RelievedAmounts": { "description": "What one leg gave up, or would give up, in its document currency and in both books of the company.", "required": [ "document", "functional", "reporting", "document_currency", "functional_currency", "reporting_currency" ], "properties": { "document": { "type": "string", "example": "300.00" }, "functional": { "type": "string", "example": "39000.00" }, "reporting": { "type": "string", "example": "300.00" }, "document_currency": { "type": "string", "example": "USD" }, "functional_currency": { "type": "string", "example": "VES" }, "reporting_currency": { "type": "string", "example": "USD" } }, "type": "object" }, "CashEventRateSnapshotView": { "description": "The official valuation the advance's units were frozen at. An identity snapshot (money kept in both books) has rule identity, rate 1.00000000 and no reference, known_at or origin.", "required": [ "rule", "rate", "rate_reference", "value_date", "known_at", "origin" ], "properties": { "rule": { "type": "string", "enum": [ "publication_instant", "value_date", "identity" ] }, "rate": { "type": "string", "example": "130.00000000" }, "rate_reference": { "type": "string", "nullable": true }, "value_date": { "type": "string", "format": "date", "example": "2026-10-03" }, "known_at": { "type": "string", "format": "date-time", "example": "2026-10-02T16:00:00+00:00", "nullable": true }, "origin": { "type": "string", "nullable": true, "enum": [ "ingested", "manual" ] } }, "type": "object" }, "SupplierCreditApplicationDifference": { "description": "One per-book difference by leg and cause, signed from the company's side: positive is a realized gain, negative a loss.", "required": [ "leg", "book", "cause", "amount", "currency" ], "properties": { "leg": { "type": "string", "enum": [ "invoice", "source" ] }, "book": { "type": "string", "enum": [ "functional", "reporting" ] }, "cause": { "type": "string", "enum": [ "debt_currency", "rounding" ] }, "amount": { "type": "string", "example": "9000.00" }, "currency": { "type": "string", "example": "VES" } }, "type": "object" }, "SupplierCreditApplication": { "description": "A Supplier Credit Application: what one supplier advance relieved from one payable document of the same provider, with the Rate Snapshot its units were valued at, both legs in the three books, and the differences its entry posted.", "required": [ "id", "source", "target", "date", "source_units", "source_currency", "rate_snapshot", "invoice_relieved", "source_relieved", "differences", "reverted_at", "revertible" ], "properties": { "id": { "type": "string", "format": "uuid" }, "source": { "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "payment", "credit_note" ] }, "id": { "type": "string", "format": "uuid" } }, "type": "object" }, "target": { "required": [ "type", "id", "code", "kind" ], "properties": { "type": { "type": "string", "enum": [ "purchases_invoice" ] }, "id": { "type": "string", "format": "uuid" }, "code": { "description": "Null only when the document cannot be read.", "type": "string", "example": "PIN00012", "nullable": true }, "kind": { "description": "Null only when the document cannot be read.", "type": "string", "nullable": true, "enum": [ "regular", "opening", "debit_note" ] } }, "type": "object" }, "date": { "type": "string", "format": "date" }, "source_units": { "type": "string", "example": "300.00" }, "source_currency": { "type": "string", "example": "USD" }, "rate_snapshot": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/CashEventRateSnapshotView" } ] }, "invoice_relieved": { "$ref": "#/components/schemas/RelievedAmounts" }, "source_relieved": { "$ref": "#/components/schemas/RelievedAmounts" }, "differences": { "type": "array", "items": { "$ref": "#/components/schemas/SupplierCreditApplicationDifference" } }, "reverted_at": { "type": "string", "format": "date-time", "nullable": true }, "revertible": { "description": "Whether the application can still be unapplied on its own; the caller still needs backoffice.purchases.payments.apply-credit.", "type": "boolean" } }, "type": "object" }, "SupplierCreditApplicationList": { "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SupplierCreditApplication" } } }, "type": "object" }, "SupplierCreditApplicationPreview": { "description": "What applying the advance would record, by the same calculator, rate rule and readiness as applying, with nothing written.", "required": [ "source", "target", "date", "source_units", "source_currency", "source_available", "units_to_settle_in_full", "derived_debt", "debt_currency", "settles_in_full", "rate_snapshot", "invoice_relieved", "invoice_open_after", "source_relieved", "source_open_after", "differences" ], "properties": { "source": { "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "payment", "credit_note" ] }, "id": { "type": "string", "format": "uuid" } }, "type": "object" }, "target": { "required": [ "type", "id", "code", "kind" ], "properties": { "type": { "type": "string", "enum": [ "purchases_invoice" ] }, "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "kind": { "type": "string", "enum": [ "regular", "opening", "debit_note" ] } }, "type": "object" }, "date": { "type": "string", "format": "date" }, "source_units": { "description": "The units previewed: those asked, or the ones proposed when none were.", "type": "string", "example": "100.00" }, "source_currency": { "type": "string", "example": "USD" }, "source_available": { "description": "What the advance holds now.", "type": "string", "example": "500.00" }, "units_to_settle_in_full": { "description": "The units that settle the document's open balance in full at this snapshot.", "type": "string", "example": "184.62" }, "derived_debt": { "type": "string", "example": "13000.00" }, "debt_currency": { "type": "string", "example": "VES" }, "settles_in_full": { "type": "boolean" }, "rate_snapshot": { "$ref": "#/components/schemas/CashEventRateSnapshotView" }, "invoice_relieved": { "$ref": "#/components/schemas/RelievedAmounts" }, "invoice_open_after": { "$ref": "#/components/schemas/RelievedAmounts" }, "source_relieved": { "$ref": "#/components/schemas/RelievedAmounts" }, "source_open_after": { "$ref": "#/components/schemas/RelievedAmounts" }, "differences": { "type": "array", "items": { "$ref": "#/components/schemas/SupplierCreditApplicationDifference" } } }, "type": "object" }, "ProviderCreditBalances": { "description": "What a provider's paid-out supplier advances still hold, per currency, under balances; empty when none does. balances lists advances only, unlike the client's body where it is Customer Credit. Beside it, supplier_credit_balances lists the provider's Supplier Credit per currency (MER-3281), never summed with the advances; credit_notes is empty for a caller without backoffice.purchases.credit-notes.view, the amounts stay. Each currency's reporting_balance is its equivalent in reporting_currency (MER-3281): the stored reporting-book Carrying Amount of its advances summed within that currency, a book value never converted at today's rate.", "required": [ "provider_id", "reporting_currency", "balances", "supplier_credit_balances" ], "properties": { "provider_id": { "type": "string", "format": "uuid" }, "reporting_currency": { "description": "The company's reporting currency, in which every reporting_balance is stated.", "type": "string", "example": "USD" }, "balances": { "type": "array", "items": { "required": [ "currency", "balance", "reporting_balance", "advances" ], "properties": { "currency": { "type": "string", "example": "USD" }, "balance": { "type": "string", "example": "700.00" }, "reporting_balance": { "description": "The stored reporting-book Carrying Amount of the currency's advances, in reporting_currency; never a conversion at today's rate.", "type": "string", "example": "700.00" }, "advances": { "type": "array", "items": { "required": [ "id", "code", "date_payment_applied", "balance" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string", "example": "PGO00012" }, "date_payment_applied": { "type": "string", "format": "date" }, "balance": { "type": "string", "example": "200.00" } }, "type": "object" } } }, "type": "object" } }, "supplier_credit_balances": { "description": "Supplier Credit, shown for information: it cannot be applied to other invoices yet.", "type": "array", "items": { "required": [ "currency", "balance", "reporting_balance", "credit_notes" ], "properties": { "currency": { "type": "string", "example": "VES" }, "balance": { "type": "string", "example": "500.00" }, "reporting_balance": { "description": "The stored reporting-book Carrying Amount of the currency's notes, in reporting_currency; never a conversion at today's rate.", "type": "string", "example": "4.17" }, "credit_notes": { "type": "array", "items": { "required": [ "id", "code", "emission_date", "balance" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string", "example": "NCP2600002" }, "emission_date": { "type": "string", "format": "date" }, "balance": { "type": "string", "example": "500.00" } }, "type": "object" } } }, "type": "object" } } }, "type": "object" }, "PurchasesCreditNoteLineInput": { "description": "One line of a Supplier Credit Note, crediting one line of its origin purchases invoice. A unit_return states `units` and is valued at the origin line's net unit price (what the line still has to credit ÷ its units still creditable); an amount_rebate states `amount`. Either way the credit is positive and within what the origin line still has after its approved credit notes.", "required": [ "id", "origin_purchases_invoice_item_id", "line_type" ], "properties": { "id": { "description": "Client-generated line id, unique within the note; a repeated request must repeat it.", "type": "string", "format": "uuid", "example": "0199a000-0000-7000-8000-0000000003b1" }, "origin_purchases_invoice_item_id": { "description": "The origin invoice line this line credits; each origin line at most once per note.", "type": "string", "format": "uuid", "example": "0199a000-0000-7000-8000-0000000000b1" }, "line_type": { "type": "string", "example": "amount_rebate", "enum": [ "unit_return", "amount_rebate" ] }, "units": { "description": "Required for a unit_return and prohibited otherwise: the units given back, greater than zero, at most 4 decimals.", "type": "string", "pattern": "^(?!0+(?:\\.0{1,4})?$)\\d{1,11}(?:\\.\\d{1,4})?$", "example": "2" }, "amount": { "description": "Required for an amount_rebate and prohibited otherwise: the amount credited in the origin's currency, greater than zero, at most 2 decimals.", "type": "string", "pattern": "^(?!0+(?:\\.0{1,2})?$)\\d{1,13}(?:\\.\\d{1,2})?$", "example": "20.00" } }, "type": "object", "additionalProperties": false }, "PurchasesCapturedAmountInput": { "description": "The base and tax of one tax group as printed on the provider's fiscal document, in the statutory books currency.", "required": [ "tax_id", "tax_percentage", "base", "tax" ], "properties": { "tax_id": { "type": "string", "format": "uuid", "example": "0199a000-0000-7000-8000-0000000000d1" }, "tax_percentage": { "type": "string", "pattern": "^(?:0*(?:[0-9]|[1-9][0-9])(?:\\.[0-9]{1,2})?|0*100(?:\\.0{1,2})?)$", "example": "16.00" }, "base": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,2})?$", "example": "730.00" }, "tax": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,2})?$", "example": "116.80" } }, "type": "object" }, "PurchasesCreditNoteRegistered": { "required": [ "purchase_credit_note_id", "code" ], "properties": { "purchase_credit_note_id": { "type": "string", "format": "uuid" }, "code": { "description": "The note's internal code: NCP, the two-digit year and its own five-digit correlative.", "type": "string", "example": "NCP2600001" } }, "type": "object" }, "PurchasesCreditNoteApproved": { "description": "What an approval did; a repeated approval answers the same.", "required": [ "purchase_credit_note_id", "status", "currency", "applied_amount", "supplier_credit", "credit_application_id" ], "properties": { "purchase_credit_note_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "example": "applied", "enum": [ "with_supplier_credit", "applied" ] }, "currency": { "type": "string", "example": "USD" }, "applied_amount": { "description": "What relieved the origin, in the note's currency; 0.00 when the origin owed nothing.", "type": "string", "example": "100.00" }, "supplier_credit": { "description": "What the note keeps as Supplier Credit.", "type": "string", "example": "0.00" }, "credit_application_id": { "description": "The Supplier Credit Application; null when nothing applied.", "type": "string", "format": "uuid", "nullable": true } }, "type": "object" }, "PurchasesCreditNoteCancelled": { "description": "What a cancellation did; a repeated cancellation answers the same note with restored_amount 0.00.", "required": [ "purchase_credit_note_id", "status", "currency", "restored_amount" ], "properties": { "purchase_credit_note_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "example": "cancelled", "enum": [ "cancelled" ] }, "currency": { "type": "string", "example": "USD" }, "restored_amount": { "description": "What this call gave back to the origin, in the note's currency; 0.00 for a draft, a note kept whole as Supplier Credit, or a repeated cancellation.", "type": "string", "example": "38.66" } }, "type": "object" }, "PurchasesDocumentProviderNumberConflict": { "description": "The provider invoice number already belongs to another live document of this provider within the same kind group: the invoices share one, each note kind has its own.", "required": [ "title", "status", "detail", "error_code", "existing_code", "existing_kind" ], "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "detail": { "type": "string", "example": "El número de factura del proveedor ya está registrado en la nota de crédito de proveedor NCP2600001" }, "error_code": { "type": "string", "enum": [ "purchases_invoice_provider_number_already_registered" ] }, "existing_code": { "description": "The code of the document that holds the number, or empty when a concurrent commit leaves the failure path unable to name it.", "type": "string", "example": "NCP2600001" }, "existing_kind": { "description": "The kind of that document. Null exactly when existing_code is empty.", "type": "string", "example": "credit_note", "nullable": true, "enum": [ "regular", "opening", "credit_note", "debit_note" ] } }, "type": "object" }, "PurchasesCreditNoteLineCapExceeded": { "description": "A line asks for more than its origin line still has to credit after the approved credit notes.", "required": [ "error", "detail", "line_id", "available_units", "available_amount", "currency" ], "properties": { "error": { "type": "string", "enum": [ "line_credit_cap_exceeded" ] }, "detail": { "type": "string" }, "line_id": { "description": "The origin invoice line whose cap was exceeded.", "type": "string", "format": "uuid" }, "available_units": { "type": "string", "example": "10.0000" }, "available_amount": { "type": "string", "example": "20.00" }, "currency": { "type": "string", "example": "USD" } }, "type": "object" }, "PurchasesNoteInvalidOrigin": { "description": "The document named as the note's origin cannot be credited: only an approved regular purchases invoice can.", "required": [ "title", "status", "detail", "error_code", "cause" ], "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string" }, "error_code": { "type": "string", "enum": [ "purchase_note_invalid_origin" ] }, "cause": { "description": "without_valuation only on approval: the origin kept no frozen valuation of a tax group the note credits.", "type": "string", "example": "not_approved", "enum": [ "not_found", "opening", "not_approved", "cancelled", "is_a_note", "without_valuation" ] }, "errors": { "type": "object", "example": null, "nullable": true } }, "type": "object" }, "PurchasesCreditNoteLine": { "description": "A line of a Supplier Credit Note: it keeps its origin line's category, item, unit, tax, center and account.", "required": [ "id", "origin_purchases_invoice_item_id", "line_type", "units", "amount", "category_id", "item_id", "item_name", "unit_id", "tax_id", "tax_percentage", "tax_kind", "accounting_center_id", "accounting_account_id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "origin_purchases_invoice_item_id": { "type": "string", "format": "uuid" }, "line_type": { "type": "string", "enum": [ "unit_return", "amount_rebate" ] }, "units": { "description": "The units a unit_return gives back; null for an amount_rebate.", "type": "string", "example": "2.0000", "nullable": true }, "amount": { "description": "The valued credit, in the note's currency.", "type": "string", "example": "20.00" }, "category_id": { "type": "string", "format": "uuid" }, "item_id": { "type": "string", "format": "uuid" }, "item_name": { "description": "The name of the line's catalog item (MER-3292); null when the item is out of the company's reach.", "type": "string", "example": "Servicio (ficticio)", "nullable": true }, "unit_id": { "type": "string", "format": "uuid" }, "tax_id": { "type": "string", "format": "uuid" }, "tax_percentage": { "type": "string", "example": "16.00" }, "tax_kind": { "type": "string", "example": "vat_general" }, "accounting_center_id": { "type": "string", "format": "uuid" }, "accounting_account_id": { "type": "string", "format": "uuid" } }, "type": "object" }, "PurchasesCapturedAmount": { "required": [ "tax_id", "tax_percentage", "base", "tax" ], "properties": { "tax_id": { "type": "string", "format": "uuid" }, "tax_percentage": { "type": "string", "example": "16.00" }, "base": { "type": "string", "example": "730.00" }, "tax": { "type": "string", "example": "116.80" } }, "type": "object" }, "PurchasesCreditNoteDetail": { "required": [ "id", "code", "kind", "status", "origin_purchases_invoice_id", "origin_code", "origin_provider_invoice_number", "origin_control_number", "origin_emission_date", "provider_id", "provider_name", "payment_term", "emission_date", "accounting_center_id", "accounting_account_payable_id", "location_id", "reason", "reason_label", "observations", "provider_invoice_number", "control_number", "provider_fiscal_snapshot", "subtotal", "discount", "taxes", "total", "balance", "captured_amounts", "lines", "tax_summaries", "applications", "company_id", "currency", "registration_date", "functional_currency", "reporting_currency", "functional_total", "reporting_total", "functional_balance", "reporting_balance", "rate_snapshot", "labels" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string", "example": "NCP2600001" }, "kind": { "type": "string", "enum": [ "credit_note" ] }, "status": { "description": "to_be_approved is a draft; an approved note keeps Supplier Credit (with_supplier_credit) or has applied all of it to its origin (applied). cancelled: an approved note's balances read its full valuation again, informative, never Supplier Credit; a cancelled draft reads 0.00.", "type": "string", "example": "to_be_approved", "enum": [ "to_be_approved", "with_supplier_credit", "applied", "cancelled" ] }, "origin_purchases_invoice_id": { "type": "string", "format": "uuid" }, "origin_code": { "description": "Null when the origin is out of reach.", "type": "string", "example": "PIN260000123", "nullable": true }, "origin_provider_invoice_number": { "type": "string", "nullable": true }, "origin_control_number": { "type": "string", "nullable": true }, "origin_emission_date": { "type": "string", "format": "date", "nullable": true }, "provider_id": { "type": "string", "format": "uuid" }, "provider_name": { "type": "string", "nullable": true }, "payment_term": { "type": "string", "enum": [ "cash", "five_days", "seven_days", "fifteen_days", "thirty_days" ] }, "emission_date": { "type": "string", "format": "date" }, "accounting_center_id": { "type": "string", "format": "uuid" }, "accounting_account_payable_id": { "type": "string", "format": "uuid" }, "location_id": { "type": "string", "format": "uuid", "nullable": true }, "reason": { "type": "string", "enum": [ "return", "discount", "price_correction", "quantity_correction", "other" ] }, "reason_label": { "type": "string", "example": "Descuento o rebaja" }, "observations": { "type": "string", "nullable": true }, "provider_invoice_number": { "type": "string", "example": "NC-45", "nullable": true }, "control_number": { "type": "string", "nullable": true }, "provider_fiscal_snapshot": { "description": "The origin's provider fiscal snapshot, as the invoice detail publishes it.", "type": "object", "nullable": true }, "subtotal": { "type": "string", "example": "20.00" }, "discount": { "type": "string", "example": "0.00" }, "taxes": { "type": "string", "example": "3.20" }, "total": { "type": "string", "example": "23.20" }, "balance": { "description": "The Supplier Credit once approved; 0.00 while the note is a draft. Once an approved note is cancelled it reads its full valuation again, informative, never Supplier Credit; a cancelled draft reads 0.00.", "type": "string", "example": "0.00" }, "captured_amounts": { "type": "array", "items": { "$ref": "#/components/schemas/PurchasesCapturedAmount" }, "nullable": true }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/PurchasesCreditNoteLine" } }, "tax_summaries": { "description": "The approved valuation once approved, one per tax group; while a draft, filled only when captures exist, as a preview at the origin's rate.", "type": "array", "items": { "type": "object" } }, "applications": { "description": "Every Supplier Credit Application of the note, active and reverted, by application date, then the order recorded, then id (MER-3292). [] for a draft, or for a note approved while its origin owed nothing.", "type": "array", "items": { "$ref": "#/components/schemas/SupplierCreditApplicationSummary" } }, "company_id": { "type": "string", "format": "uuid" }, "currency": { "type": "string", "example": "USD" }, "registration_date": { "type": "string", "format": "date" }, "functional_currency": { "type": "string", "example": "VES" }, "reporting_currency": { "type": "string", "example": "USD" }, "functional_total": { "description": "An estimate until approval, final once approved.", "type": "string" }, "reporting_total": { "description": "An estimate until approval, final once approved.", "type": "string" }, "functional_balance": { "type": "string", "example": "0.00" }, "reporting_balance": { "type": "string", "example": "0.00" }, "rate_snapshot": { "description": "The origin's frozen snapshot, as the invoice detail publishes it.", "type": "object" }, "labels": { "description": "Company labels assigned to this note. Empty when it has none.", "type": "array", "items": { "required": [ "id", "name", "tone", "archived" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "tone": { "type": "string", "enum": [ "red", "orange", "blue", "violet", "teal" ] }, "archived": { "type": "boolean" } }, "type": "object" } } }, "type": "object" }, "SupplierCreditApplicationSummary": { "description": "A Supplier Credit Application as its note's detail lists it (MER-3292).", "required": [ "id", "purchases_invoice_id", "purchases_invoice_code", "application_date", "amount", "currency", "reverted_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "purchases_invoice_id": { "description": "The invoice it relieves; today always the note's origin.", "type": "string", "format": "uuid" }, "purchases_invoice_code": { "description": "Null only when that invoice cannot be read.", "type": "string", "example": "PIN2600042", "nullable": true }, "application_date": { "description": "The note's Registration Date.", "type": "string", "format": "date", "example": "2026-09-29" }, "amount": { "description": "What the note gave up, in currency.", "type": "string", "example": "50.00" }, "currency": { "description": "The note's currency.", "type": "string", "example": "USD", "enum": [ "USD", "VES" ] }, "reverted_at": { "description": "UTC Y-m-d H:i:s once the note's cancellation reverted it; null while active.", "type": "string", "example": "2026-10-02 16:00:00", "nullable": true } }, "type": "object" }, "PurchasesInvoiceCreditableLine": { "required": [ "origin_purchases_invoice_item_id", "category_id", "item_id", "item_name", "unit_id", "tax_id", "tax_percentage", "tax_kind", "invoiced_units", "invoiced_amount", "increased_units", "increased_amount", "credited_units", "credited_amount", "available_units", "available_amount" ], "properties": { "origin_purchases_invoice_item_id": { "type": "string", "format": "uuid" }, "category_id": { "type": "string", "format": "uuid" }, "item_id": { "type": "string", "format": "uuid" }, "item_name": { "description": "The name of the line's catalog item (MER-3292); null when the item is out of the company's reach.", "type": "string", "example": "Servicio (ficticio)", "nullable": true }, "unit_id": { "type": "string", "format": "uuid" }, "tax_id": { "type": "string", "format": "uuid" }, "tax_percentage": { "type": "string", "example": "16.00" }, "tax_kind": { "type": "string", "example": "vat_general" }, "invoiced_units": { "type": "string", "example": "10.0000" }, "invoiced_amount": { "description": "Net of the line discount.", "type": "string", "example": "100.00" }, "increased_units": { "description": "Units the approved supplier debit notes added to the line (MER-3291); 0.0000 for increases by amount.", "type": "string", "example": "2.0000" }, "increased_amount": { "description": "Amount the approved supplier debit notes added to the line (MER-3291); their new concepts never count.", "type": "string", "example": "20.00" }, "credited_units": { "type": "string", "example": "0.0000" }, "credited_amount": { "type": "string", "example": "80.00" }, "available_units": { "type": "string", "example": "10.0000" }, "available_amount": { "type": "string", "example": "20.00" } }, "type": "object" }, "PurchasesInvoiceCreditableLines": { "required": [ "origin_purchases_invoice_id", "origin_code", "origin_provider_invoice_number", "origin_emission_date", "provider_id", "currency", "rate_snapshot", "lines" ], "properties": { "origin_purchases_invoice_id": { "type": "string", "format": "uuid" }, "origin_code": { "type": "string", "example": "PIN260000123" }, "origin_provider_invoice_number": { "type": "string", "example": "00012345", "nullable": true }, "origin_emission_date": { "type": "string", "format": "date" }, "provider_id": { "type": "string", "format": "uuid" }, "currency": { "type": "string", "example": "USD" }, "rate_snapshot": { "description": "The origin's frozen snapshot, as the invoice detail publishes it.", "type": "object" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/PurchasesInvoiceCreditableLine" } } }, "type": "object" }, "PurchasesNoteOriginSource": { "required": [ "id", "code", "kind", "status", "provider_name", "provider_invoice_number", "control_number", "emission_date", "currency", "rate_snapshot", "accounting_center_id", "provider_fiscal_snapshot", "items" ], "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "kind": { "type": "string" }, "status": { "type": "string" }, "provider_name": { "type": "string", "nullable": true }, "provider_invoice_number": { "type": "string", "nullable": true }, "control_number": { "type": "string", "nullable": true }, "emission_date": { "type": "string" }, "currency": { "type": "string" }, "accounting_center_id": { "type": "string" }, "rate_snapshot": { "properties": { "currency": { "type": "string" }, "functional_rate": { "type": "string" }, "functional_rate_reference": { "type": "string", "nullable": true }, "reporting_rate": { "type": "string" }, "reporting_rate_reference": { "type": "string", "nullable": true }, "rate_rule": { "type": "string" }, "rate_value_date": { "type": "string" }, "rate_known_at": { "type": "string", "nullable": true }, "rate_origin": { "type": "string", "nullable": true } }, "type": "object" }, "provider_fiscal_snapshot": { "properties": { "document_type": { "type": "string", "nullable": true }, "document_number": { "type": "string", "nullable": true }, "legal_name": { "type": "string", "nullable": true }, "vat_taxpayer_type": { "type": "string", "nullable": true }, "special_taxpayer_since": { "type": "string", "nullable": true }, "islr_person_type": { "type": "string", "nullable": true } }, "type": "object", "nullable": true }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/PurchasesNoteOriginLine" } } }, "type": "object" }, "PurchasesNoteOriginLine": { "required": [ "id", "item_id", "item_name", "quantity", "unit_price", "discount_percentage", "tax_id", "tax_percentage", "tax_kind" ], "properties": { "id": { "type": "string" }, "item_id": { "type": "string" }, "item_name": { "type": "string", "nullable": true }, "quantity": { "type": "string" }, "unit_price": { "type": "string" }, "discount_percentage": { "type": "string" }, "tax_id": { "type": "string" }, "tax_percentage": { "type": "string" }, "tax_kind": { "type": "string" } }, "type": "object" }, "PurchasesDebitNoteLineInput": { "description": "One line of a Supplier Debit Note. A linked_increase raises one line of its origin: it states `units`, valued at the origin line's net unit price (net amount × units ÷ invoiced units, half-up), or `amount`, never both, and inherits the origin line's category, item, unit, tax, expense account and center. A new_concept brings a concept the origin never had, with its own category, item, unit, quantity, unit price, expense account and center, priced like an invoice line with no discount and taxed by one of the origin's tax groups.", "required": [ "id", "line_type" ], "properties": { "id": { "description": "Client-generated line id, unique within the note; a repeated request must repeat it.", "type": "string", "format": "uuid" }, "line_type": { "type": "string", "enum": [ "linked_increase", "new_concept" ] }, "origin_purchases_invoice_item_id": { "description": "Required for a linked_increase and prohibited otherwise: the origin line it raises, each at most once per note.", "type": "string", "format": "uuid" }, "units": { "description": "Only on a linked_increase, and never with amount: the units added, greater than zero, at most 4 decimals.", "type": "string", "pattern": "^(?!0+(?:\\.0{1,4})?$)\\d{1,11}(?:\\.\\d{1,4})?$", "example": "2" }, "amount": { "description": "Only on a linked_increase, and never with units: the amount added in the origin's currency, greater than zero, at most 2 decimals.", "type": "string", "pattern": "^(?!0+(?:\\.0{1,2})?$)\\d{1,13}(?:\\.\\d{1,2})?$", "example": "17.24" }, "category_id": { "description": "Required for a new_concept and prohibited otherwise.", "type": "string", "format": "uuid" }, "item_id": { "description": "Required for a new_concept and prohibited otherwise.", "type": "string", "format": "uuid" }, "unit_id": { "description": "Required for a new_concept and prohibited otherwise.", "type": "string", "format": "uuid" }, "quantity": { "description": "Required for a new_concept and prohibited otherwise: greater than zero, at most 4 decimals.", "type": "string", "pattern": "^(?!0+(?:\\.0{1,4})?$)\\d{1,11}(?:\\.\\d{1,4})?$", "example": "1" }, "unit_price": { "description": "Required for a new_concept and prohibited otherwise, at most 2 decimals.", "type": "string", "pattern": "^\\d+(\\.\\d{1,2})?$", "example": "5.00" }, "tax_id": { "description": "Required for a new_concept and prohibited otherwise: the tax of one of the origin's tax groups.", "type": "string", "format": "uuid" }, "tax_percentage": { "description": "Required for a new_concept and prohibited otherwise: the rate of that origin tax group.", "type": "string", "pattern": "^(?:0*(?:[0-9]|[1-9][0-9])(?:\\.[0-9]{1,2})?|0*100(?:\\.0{1,2})?)$", "example": "16.00" }, "accounting_center_id": { "description": "Required for a new_concept and prohibited otherwise: the center its expense posts to.", "type": "string", "format": "uuid" }, "accounting_account_id": { "description": "Required for a new_concept and prohibited otherwise: the expense account it posts to.", "type": "string", "format": "uuid" } }, "type": "object", "additionalProperties": false }, "PurchasesDebitNoteRegistered": { "required": [ "purchase_debit_note_id", "code" ], "properties": { "purchase_debit_note_id": { "type": "string", "format": "uuid" }, "code": { "description": "The note's internal code: NDP, the two-digit year and its own five-digit correlative.", "type": "string", "example": "NDP2600001" } }, "type": "object" }, "PurchasesDebitNoteApproved": { "description": "What an approval left; a repeated approval answers the note's current status.", "required": [ "purchase_debit_note_id", "code", "status", "currency", "total", "withheld_amount", "balance", "functional_total", "reporting_total" ], "properties": { "purchase_debit_note_id": { "type": "string", "format": "uuid" }, "code": { "type": "string", "example": "NDP2600001" }, "status": { "type": "string", "example": "to_be_paid", "enum": [ "to_be_paid", "partially_paid", "fully_paid" ] }, "currency": { "type": "string", "example": "USD" }, "total": { "description": "What the note owes, in its currency.", "type": "string", "example": "20.00" }, "withheld_amount": { "description": "What its VAT and ISLR withholdings withheld, in its currency (MER-5386); 0.00 when it withholds nothing.", "type": "string", "example": "2.40" }, "balance": { "description": "What it still owes the supplier, in its currency: its total less what was withheld and paid.", "type": "string", "example": "17.60" }, "functional_total": { "description": "Its total in the functional book, at the origin's frozen rate.", "type": "string", "example": "730.80" }, "reporting_total": { "description": "Its total in the reporting book.", "type": "string", "example": "20.00" } }, "type": "object" }, "PurchasesDebitNoteCancelled": { "description": "What a cancellation did; a repeated cancellation answers the same note with reversed_amount 0.00.", "required": [ "purchase_debit_note_id", "status", "currency", "reversed_amount" ], "properties": { "purchase_debit_note_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "example": "cancelled", "enum": [ "cancelled" ] }, "currency": { "type": "string", "example": "USD" }, "reversed_amount": { "description": "What this call reversed of the note's approved entry, in the note's currency: its total for an approved note; 0.00 for a draft or a repeated cancellation.", "type": "string", "example": "20.00" } }, "type": "object" }, "PurchasesDebitNoteCancellationConflict": { "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "detail": { "type": "string" }, "error_code": { "type": "string", "enum": [ "purchase_debit_note_has_payments", "purchase_debit_note_increase_credited", "document_in_frozen_fiscal_period", "inventory_cost_revaluation_raced" ] }, "errors": { "type": "object", "nullable": true }, "origin_purchases_invoice_item_ids": { "description": "Only on purchase_debit_note_increase_credited: the origin lines the note raised that an approved credit note credits beyond what they would keep.", "type": "array", "items": { "type": "string", "format": "uuid" } }, "credit_notes": { "description": "Only on purchase_debit_note_increase_credited: the origin's approved credit notes, in id order; cancel the one that credits the increase first.", "type": "array", "items": { "required": [ "id", "code", "kind", "status" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string", "example": "NCP2600003" }, "kind": { "type": "string", "enum": [ "credit_note" ] }, "status": { "type": "string", "enum": [ "with_supplier_credit", "applied" ] } }, "type": "object" } }, "fiscal_period": { "description": "Only on document_in_frozen_fiscal_period (MER-3837): the period whose current Declared Set holds the note.", "allOf": [ { "$ref": "#/components/schemas/FrozenFiscalPeriod" } ] } }, "type": "object" }, "PurchasesDebitNoteLine": { "description": "A line of a Supplier Debit Note: a linked_increase keeps its origin line's category, item, unit, tax, account and center; a new_concept its own, taxed in an origin group.", "required": [ "id", "line_type", "origin_purchases_invoice_item_id", "units", "amount", "quantity", "unit_price", "category_id", "item_id", "item_name", "unit_id", "tax_id", "tax_percentage", "tax_kind", "accounting_center_id", "accounting_account_id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "line_type": { "type": "string", "enum": [ "linked_increase", "new_concept" ] }, "origin_purchases_invoice_item_id": { "description": "The origin line a linked_increase raises; null for a new_concept.", "type": "string", "format": "uuid", "nullable": true }, "units": { "description": "The units a linked_increase adds; null when it states an amount, and for a new_concept.", "type": "string", "example": "2.0000", "nullable": true }, "amount": { "description": "The line's value, in the note's currency.", "type": "string", "example": "17.24" }, "quantity": { "description": "A new_concept's quantity; null for a linked_increase.", "type": "string", "example": "1.0000", "nullable": true }, "unit_price": { "description": "A new_concept's unit price; null for a linked_increase.", "type": "string", "example": "5.00", "nullable": true }, "category_id": { "type": "string", "format": "uuid" }, "item_id": { "type": "string", "format": "uuid" }, "item_name": { "description": "The name of the line's catalog item (MER-3292); null when the item is out of the company's reach.", "type": "string", "example": "Servicio (ficticio)", "nullable": true }, "unit_id": { "type": "string", "format": "uuid" }, "tax_id": { "type": "string", "format": "uuid" }, "tax_percentage": { "type": "string", "example": "16.00" }, "tax_kind": { "type": "string", "example": "vat_general" }, "accounting_center_id": { "type": "string", "format": "uuid" }, "accounting_account_id": { "type": "string", "format": "uuid" } }, "type": "object" }, "PurchasesDebitNoteDetail": { "required": [ "id", "code", "kind", "status", "origin_purchases_invoice_id", "origin_code", "origin_provider_invoice_number", "origin_control_number", "origin_emission_date", "provider_id", "provider_name", "payment_term", "emission_date", "accounting_center_id", "accounting_account_payable_id", "location_id", "reason", "reason_label", "observations", "provider_invoice_number", "control_number", "provider_fiscal_snapshot", "subtotal", "discount", "taxes", "total", "withheld_amount", "balance", "captured_amounts", "lines", "tax_summaries", "company_id", "currency", "registration_date", "functional_currency", "reporting_currency", "functional_total", "reporting_total", "functional_balance", "reporting_balance", "rate_snapshot", "labels" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string", "example": "NDP2600001" }, "kind": { "type": "string", "enum": [ "debit_note" ] }, "status": { "description": "to_be_approved is a draft; an approved note is to_be_paid, then partially_paid or fully_paid through payments; cancelled keeps its balances as they stood, informative.", "type": "string", "example": "to_be_approved", "enum": [ "to_be_approved", "to_be_paid", "partially_paid", "fully_paid", "cancelled" ] }, "origin_purchases_invoice_id": { "type": "string", "format": "uuid" }, "origin_code": { "description": "Null when the origin is out of reach.", "type": "string", "example": "PIN260000123", "nullable": true }, "origin_provider_invoice_number": { "type": "string", "nullable": true }, "origin_control_number": { "type": "string", "nullable": true }, "origin_emission_date": { "type": "string", "format": "date", "nullable": true }, "provider_id": { "type": "string", "format": "uuid" }, "provider_name": { "type": "string", "nullable": true }, "payment_term": { "type": "string", "enum": [ "cash", "five_days", "seven_days", "fifteen_days", "thirty_days" ] }, "emission_date": { "type": "string", "format": "date" }, "accounting_center_id": { "type": "string", "format": "uuid" }, "accounting_account_payable_id": { "type": "string", "format": "uuid" }, "location_id": { "type": "string", "format": "uuid", "nullable": true }, "reason": { "type": "string", "enum": [ "interest", "freight", "price_correction", "quantity_correction", "other" ] }, "reason_label": { "type": "string", "example": "Corrección de precio" }, "observations": { "type": "string", "nullable": true }, "provider_invoice_number": { "type": "string", "example": "ND-000123", "nullable": true }, "control_number": { "type": "string", "nullable": true }, "provider_fiscal_snapshot": { "description": "The origin's provider fiscal snapshot, as the invoice detail publishes it.", "type": "object", "nullable": true }, "subtotal": { "type": "string", "example": "17.24" }, "discount": { "type": "string", "example": "0.00" }, "taxes": { "type": "string", "example": "2.76" }, "total": { "type": "string", "example": "20.00" }, "withheld_amount": { "description": "What its VAT and ISLR withholdings withheld, in its currency (MER-5386): 0.00 while a draft, when it withholds nothing and once its withholdings are voided.", "type": "string", "example": "0.00" }, "balance": { "description": "The open debt: 0.00 while a draft, the total less what its withholdings withheld once approved, what remains after payments, and as it stood once cancelled.", "type": "string", "example": "0.00" }, "captured_amounts": { "type": "array", "items": { "$ref": "#/components/schemas/PurchasesCapturedAmount" }, "nullable": true }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/PurchasesDebitNoteLine" } }, "tax_summaries": { "description": "The approved valuation once approved, one per tax group; while a draft, filled only when captures exist, as a preview at the origin's rate.", "type": "array", "items": { "type": "object" } }, "company_id": { "type": "string", "format": "uuid" }, "currency": { "type": "string", "example": "USD" }, "registration_date": { "description": "The period its VAT input lands in.", "type": "string", "format": "date" }, "functional_currency": { "type": "string", "example": "VES" }, "reporting_currency": { "type": "string", "example": "USD" }, "functional_total": { "description": "An estimate until approval, final once approved.", "type": "string" }, "reporting_total": { "description": "An estimate until approval, final once approved.", "type": "string" }, "functional_balance": { "type": "string", "example": "0.00" }, "reporting_balance": { "type": "string", "example": "0.00" }, "rate_snapshot": { "description": "The origin's frozen snapshot, as the invoice detail publishes it.", "type": "object" }, "labels": { "description": "Company labels assigned to this note. Empty when it has none.", "type": "array", "items": { "required": [ "id", "name", "tone", "archived" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "tone": { "type": "string", "enum": [ "red", "orange", "blue", "violet", "teal" ] }, "archived": { "type": "boolean" } }, "type": "object" } } }, "type": "object" }, "OrderProblem": { "description": "Controller validation and domain errors for Orders (pedidos internos). Validation has a null error_code and an errors object mapping field names to messages. A domain refusal has an error_code; its errors is null, except `purchase_line_item_mismatch`, whose errors names each refused line field (items.N.category_id, items.N.unit_id).", "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "error_code": { "type": "string", "nullable": true }, "errors": { "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" }, "OrderRequestValidation": { "description": "Laravel request validation, answered before the controller runs.", "required": [ "message", "errors" ], "properties": { "message": { "type": "string" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" }, "PayablesAgingAmount": { "type": "string", "pattern": "^-?[0-9]+[.][0-9]{2}$", "example": "300.00" }, "PayablesAgingMessageError": { "required": [ "message" ], "properties": { "message": { "type": "string" } }, "type": "object" }, "PayablesAgingValidationError": { "required": [ "message", "errors" ], "properties": { "message": { "type": "string" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" }, "PayablesAgingForbiddenError": { "required": [ "title", "status", "detail" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "reason": { "type": "string" } }, "type": "object" }, "PayablesAgingProblem": { "required": [ "title", "status", "detail", "error_code" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "error_code": { "type": "string", "nullable": true }, "errors": { "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" }, "PayablesAgingRow": { "description": "One provider's open payables in one document currency. Buckets, credit and total are in that currency; total = current + d1_30 + d31_60 + d61_90 + over_90 + credit.", "required": [ "counterparty_id", "counterparty_code", "counterparty_name", "currency", "current", "d1_30", "d31_60", "d61_90", "over_90", "credit", "total", "reporting_total", "functional_total", "has_approximate_due_dates" ], "properties": { "counterparty_id": { "description": "The provider id", "type": "string", "format": "uuid" }, "counterparty_code": { "description": "Null only when the provider row is missing, an integrity anomaly; the name is then empty", "type": "string", "nullable": true }, "counterparty_name": { "type": "string" }, "currency": { "type": "string", "enum": [ "USD", "VES", "USDT", "EUR", "DOP" ] }, "current": { "$ref": "#/components/schemas/PayablesAgingAmount" }, "d1_30": { "$ref": "#/components/schemas/PayablesAgingAmount" }, "d31_60": { "$ref": "#/components/schemas/PayablesAgingAmount" }, "d61_90": { "$ref": "#/components/schemas/PayablesAgingAmount" }, "over_90": { "$ref": "#/components/schemas/PayablesAgingAmount" }, "credit": { "description": "Supplier Credit still held by the provider's credit notes, zero or negative; already subtracted from total and both book totals.", "allOf": [ { "$ref": "#/components/schemas/PayablesAgingAmount" } ] }, "total": { "$ref": "#/components/schemas/PayablesAgingAmount" }, "reporting_total": { "description": "Stored reporting-book balances", "allOf": [ { "$ref": "#/components/schemas/PayablesAgingAmount" } ] }, "functional_total": { "description": "Stored functional-book balances", "allOf": [ { "$ref": "#/components/schemas/PayablesAgingAmount" } ] }, "has_approximate_due_dates": { "description": "An invoice or debit note was aged without its exact due date: an opening invoice without its Opening Document, or a stored payment term outside the known vocabulary, aged from its emission date", "type": "boolean" } }, "type": "object" }, "PayablesAgingCurrencyTotal": { "description": "Every row of one document currency added up; currencies are never summed together.", "required": [ "currency", "current", "d1_30", "d31_60", "d61_90", "over_90", "credit", "total", "reporting_total", "functional_total" ], "properties": { "currency": { "type": "string", "enum": [ "USD", "VES", "USDT", "EUR", "DOP" ] }, "current": { "$ref": "#/components/schemas/PayablesAgingAmount" }, "d1_30": { "$ref": "#/components/schemas/PayablesAgingAmount" }, "d31_60": { "$ref": "#/components/schemas/PayablesAgingAmount" }, "d61_90": { "$ref": "#/components/schemas/PayablesAgingAmount" }, "over_90": { "$ref": "#/components/schemas/PayablesAgingAmount" }, "credit": { "$ref": "#/components/schemas/PayablesAgingAmount" }, "total": { "$ref": "#/components/schemas/PayablesAgingAmount" }, "reporting_total": { "$ref": "#/components/schemas/PayablesAgingAmount" }, "functional_total": { "$ref": "#/components/schemas/PayablesAgingAmount" } }, "type": "object" }, "PayablesAging": { "description": "Open payables as of today in the company timezone, one row per provider and document currency: regular and opening purchase invoices and supplier debit notes still to be paid, each aged from the provider's emission date plus its payment term (a debit note inherits its origin's), never the registration date, and each supplier credit note's Supplier Credit subtracted in credit. Unfiltered, functional_total and reporting_total equal the payable control accounts' ledger balance in each book, except while an unrealized revaluation entry on a payable account is open (ADR 0122). Any filter narrows every open document, so filtered totals do not equal the ledger.", "required": [ "as_of", "functional_currency", "reporting_currency", "has_approximate_due_dates", "rows", "totals_by_currency", "functional_total", "reporting_total" ], "properties": { "as_of": { "description": "Today in the company timezone", "type": "string", "format": "date" }, "functional_currency": { "type": "string", "enum": [ "USD", "VES", "USDT", "EUR", "DOP" ] }, "reporting_currency": { "type": "string", "enum": [ "USD", "VES", "USDT", "EUR", "DOP" ] }, "has_approximate_due_dates": { "type": "boolean" }, "rows": { "description": "Ordered by provider name, provider id and currency", "type": "array", "items": { "$ref": "#/components/schemas/PayablesAgingRow" } }, "totals_by_currency": { "description": "Ordered by currency code", "type": "array", "items": { "$ref": "#/components/schemas/PayablesAgingCurrencyTotal" } }, "functional_total": { "description": "Every row's functional_total, in the functional currency", "allOf": [ { "$ref": "#/components/schemas/PayablesAgingAmount" } ] }, "reporting_total": { "description": "Every row's reporting_total, in the reporting currency", "allOf": [ { "$ref": "#/components/schemas/PayablesAgingAmount" } ] } }, "type": "object" }, "ProviderStatementAmount": { "type": "string", "pattern": "^-?[0-9]+[.][0-9]{2}$", "example": "200.00" }, "ProviderStatementMessageError": { "required": [ "message" ], "properties": { "message": { "type": "string" } }, "type": "object" }, "ProviderStatementValidationError": { "required": [ "message", "errors" ], "properties": { "message": { "type": "string" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" }, "ProviderStatementForbiddenError": { "required": [ "title", "status", "detail" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "reason": { "type": "string" } }, "type": "object" }, "ProviderStatementProblem": { "required": [ "title", "status", "detail", "error_code" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "error_code": { "type": "string", "nullable": true }, "errors": { "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" }, "ProviderStatementProvider": { "required": [ "id", "code", "name" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "ProviderStatementRange": { "required": [ "from", "to" ], "properties": { "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" } }, "type": "object" }, "ProviderStatementLine": { "description": "One movement of what the company owes the provider inside the range with the running balance it leaves. Exactly one of debit and credit is above zero.", "required": [ "date", "type", "document_id", "document_code", "reference", "origin_document_code", "debit", "credit", "balance", "has_approximate_date" ], "properties": { "date": { "description": "The day the movement falls on in the company calendar", "type": "string", "format": "date" }, "type": { "description": "Approved invoices, opening invoices and debit notes raise what is owed by their total at their emission date; an approved credit note lowers it once by its whole total, its Supplier Credit included; a VAT withholding practised on an approved invoice lowers it by what it withheld, in the invoice's currency, on the invoice's registration date, naming the invoice as its document (MER-3107); payments lower it on their applied date by what they relieved on the provider's invoices and debit notes; an advance application lowers it by what it relieved on the invoice or debit note, in that document's currency, on its application date, and its reversal raises it back on the day of its ledger reversal entry. A cancelled invoice counts its approval and then its cancellation only when the ledger proves it was approved; a cancelled note counts its approval and then its cancellation once it had been approved. A credit note's Supplier Credit Applications are never movements: a credit note counts once; an advance's are. A voided opening invoice and a payment cancelled before it was applied move nothing. Within a day, lines follow this order, then document code", "type": "string", "enum": [ "opening_invoice", "invoice", "debit_note", "credit_note", "withholding", "payment", "advance_application", "payment_cancellation", "advance_application_reversal", "credit_note_cancellation", "debit_note_cancellation", "invoice_cancellation" ] }, "document_id": { "description": "The purchase invoice, supplier note or payment the line comes from or, for an advance application or its reversal, the advance (a payment of kind advance)", "type": "string", "format": "uuid" }, "document_code": { "description": "Internal code of the purchase invoice, supplier note or payment or, for an advance application or its reversal, of the advance (a payment of kind advance)", "type": "string" }, "reference": { "description": "The provider's own invoice or note number; null for a payment, an advance application or its reversal", "type": "string", "nullable": true }, "origin_document_code": { "description": "Internal code of the invoice a debit or credit note was issued on, or of the invoice or debit note an advance application relieved or its reversal restored; null otherwise", "type": "string", "nullable": true }, "debit": { "description": "What the line adds to what the company owes the provider, 0.00 when it lowers it; the mirror image of the payables ledger, where an invoice is a credit", "type": "string", "pattern": "^[0-9]+[.][0-9]{2}$" }, "credit": { "description": "What the line takes off what the company owes the provider, 0.00 when it raises it", "type": "string", "pattern": "^[0-9]+[.][0-9]{2}$" }, "balance": { "description": "Running balance owed to the provider after the line", "allOf": [ { "$ref": "#/components/schemas/ProviderStatementAmount" } ] }, "has_approximate_date": { "description": "True for an invoice, payment or supplier note cancellation without a stored cancelled_on day, or an advance application's reversal without a ledger reversal entry, dated on the company day of its recorded instant (a cancellation's last update, a reversal's reverted instant)", "type": "boolean" } }, "type": "object" }, "ProviderStatementTotals": { "required": [ "debits", "credits" ], "properties": { "debits": { "type": "string", "pattern": "^[0-9]+[.][0-9]{2}$" }, "credits": { "type": "string", "pattern": "^[0-9]+[.][0-9]{2}$" } }, "type": "object" }, "ProviderStatementSection": { "description": "What the company owes the provider in one document currency: closing_balance = opening_balance + totals.debits - totals.credits. Currencies are never summed.", "required": [ "currency", "opening_balance", "lines", "totals", "closing_balance" ], "properties": { "currency": { "type": "string", "enum": [ "USD", "VES", "USDT", "EUR", "DOP" ] }, "opening_balance": { "description": "Every movement dated before from", "allOf": [ { "$ref": "#/components/schemas/ProviderStatementAmount" } ] }, "lines": { "description": "Ordered by date, movement type and document code", "type": "array", "items": { "$ref": "#/components/schemas/ProviderStatementLine" } }, "totals": { "$ref": "#/components/schemas/ProviderStatementTotals" }, "closing_balance": { "description": "As of a to on or after the latest movement it equals the provider's payables aging total in this currency, live advance applications included. Lines are dated at emission while the payables ledger posts at registration, so a period's lines may differ from the ledger's", "allOf": [ { "$ref": "#/components/schemas/ProviderStatementAmount" } ] } }, "type": "object" }, "ProviderStatementOpenCredit": { "required": [ "type", "currency", "document_id", "document_code", "date", "amount" ], "properties": { "type": { "description": "supplier_credit: the Supplier Credit a credit note still holds, already included in the section balances; advance: what an open supplier advance still holds, not included in them, since an advance moves no debt until it is applied", "type": "string", "enum": [ "supplier_credit", "advance" ] }, "currency": { "type": "string", "enum": [ "USD", "VES", "USDT", "EUR", "DOP" ] }, "document_id": { "description": "The credit note or the advance payment", "type": "string", "format": "uuid" }, "document_code": { "type": "string" }, "date": { "description": "The credit note's emission date, or the day the advance was paid out", "type": "string", "format": "date" }, "amount": { "type": "string", "pattern": "^[0-9]+[.][0-9]{2}$" } }, "type": "object" }, "ProviderStatement": { "description": "Informational Account Statement of one provider over a range, one section per document currency ordered by currency code, never a fiscal document.", "required": [ "provider", "range", "currency", "as_of", "has_approximate_dates", "sections", "open_credits" ], "properties": { "provider": { "$ref": "#/components/schemas/ProviderStatementProvider" }, "range": { "$ref": "#/components/schemas/ProviderStatementRange" }, "currency": { "description": "The requested currency, null when every currency is stated", "type": "string", "nullable": true, "enum": [ "USD", "VES", "USDT", "EUR", "DOP" ] }, "as_of": { "description": "Today in the company timezone; it dates open_credits only", "type": "string", "format": "date" }, "has_approximate_dates": { "description": "Some line, or some movement folded into an opening balance, has an approximate date", "type": "boolean" }, "sections": { "type": "array", "items": { "$ref": "#/components/schemas/ProviderStatementSection" } }, "open_credits": { "description": "Supplier Credit and open advances the company holds with the provider as of as_of, independent of to, narrowed to the requested currency, by currency, then date, then document code. Supplier Credit is already included in the section balances; advances are not.", "type": "array", "items": { "$ref": "#/components/schemas/ProviderStatementOpenCredit" } } }, "type": "object" }, "PaymentDocument": { "required": [ "id", "code", "provider_id", "emission_date", "status", "total", "balance", "currency", "kind" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "provider_id": { "type": "string", "format": "uuid" }, "emission_date": { "type": "string", "format": "date" }, "status": { "type": "string" }, "total": { "type": "string" }, "balance": { "type": "string" }, "currency": { "type": "string" }, "kind": { "type": "string", "enum": [ "regular", "opening", "debit_note" ] } }, "type": "object" }, "PaymentProblem": { "description": "Controller validation and domain errors. Validation has a null error_code and an errors object mapping field names to messages. A domain refusal has an error_code; its errors is null, unless it names a method line, when errors holds that line's request field (e.g. methods.0.agreed_rate) with the refusal's message, at whatever status the refusal answers, or it is `purchases_provider_inactive` / `purchases_provider_not_found`, when errors names `provider_id`. Some refusals add members beside these five.", "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "error_code": { "type": "string", "nullable": true }, "errors": { "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" }, "PaymentLineDerivesNoDebtProblem": { "description": "payment_line_derives_no_debt (422, MER-4384): a method line's settling units (amountPaid − igtf_paid_amount) derive less than one cent of the invoices' currency, so the line would settle nothing. A line at an agreed rate is refused when the payment is created or updated, with `errors` naming `methods.N.amountPaid`; a line converting at the official rate is refused when the payment is applied, with `errors` null, and the payment stays to be applied.", "allOf": [ { "$ref": "#/components/schemas/PaymentProblem" }, { "required": [ "method_line", "units", "units_currency", "currency", "rate_basis" ], "properties": { "method_line": { "description": "The refused line's position in `methods`, counted from 0.", "type": "integer", "example": 0, "minimum": 0 }, "units": { "description": "The line's settling units, in units_currency.", "type": "string", "pattern": "^\\d+\\.\\d{2}$", "example": "0.84" }, "units_currency": { "description": "The currency the line's units are counted in.", "type": "string", "example": "VES" }, "currency": { "description": "The invoices' currency, in which the line derives no cent.", "type": "string", "example": "USD" }, "rate_basis": { "description": "The rate the units converted at: the line's agreed settlement rate, or the official rate of the day the payment is applied.", "type": "string", "example": "agreed", "enum": [ "agreed", "official" ] } }, "type": "object" } ] }, "PaymentSettlementRejectionProblem": { "description": "derived_debt_exceeds_open_balance or derived_debt_does_not_match_applied_amounts (422, MER-4384): the debt the method lines derive does not settle what the payment claims. The figures are decimal strings in `currency`, the invoices' currency; a figure the refusal has none of is null: `open` for a mismatch with the amounts applied, `applied` for a derived debt beyond the open balance.", "allOf": [ { "$ref": "#/components/schemas/PaymentProblem" }, { "required": [ "derived", "open", "applied", "currency" ], "properties": { "derived": { "description": "The debt the lines derive.", "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "72.12" }, "open": { "description": "The open balance the derived debt exceeds beyond the tolerance (derived_debt_exceeds_open_balance), otherwise null.", "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "70.00", "nullable": true }, "applied": { "description": "What the payables apply, which the derived debt does not match (derived_debt_does_not_match_applied_amounts), otherwise null.", "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "59.99", "nullable": true }, "currency": { "description": "The invoices' currency, in which every figure counts.", "type": "string", "example": "USD" } }, "type": "object" } ] }, "PaymentInvoiceBalanceProblem": { "description": "invoice_already_fully_paid or payment_exceeds_invoice_balance (400): the invoice has nothing left open, or a payable applies more than it still owes. Every amount is a decimal string in `currency`, the invoice's currency, which the detail names too (e.g. «VES 2000.00», MER-4384).", "allOf": [ { "$ref": "#/components/schemas/PaymentProblem" }, { "required": [ "invoice_code", "invoice_total", "payment_amount", "currency" ], "properties": { "invoice_code": { "description": "The refused invoice's code.", "type": "string", "example": "PI-000123" }, "invoice_total": { "description": "The invoice's total.", "type": "string", "example": "3000.00" }, "payment_amount": { "description": "What the payment would apply to the invoice.", "type": "string", "example": "2500.00" }, "available_balance": { "description": "What the invoice still owes; only payment_exceeds_invoice_balance carries it.", "type": "string", "example": "2000.00" }, "currency": { "description": "The invoice's currency, in which every amount counts.", "type": "string", "example": "VES" } }, "type": "object" } ] }, "PaymentMiddlewareError": { "description": "Authentication and tenant middleware may answer with message instead of the controller Problem shape.", "required": [ "message" ], "properties": { "message": { "type": "string" } }, "type": "object" }, "PaymentAccountingConfigurationError": { "required": [ "error", "missing" ], "properties": { "error": { "type": "string", "enum": [ "accounting_configuration_incomplete" ] }, "missing": { "type": "array", "items": { "required": [ "reason_code", "subject_type", "subject_id", "human_message", "details" ], "properties": { "reason_code": { "type": "string", "example": "SUPPLIER_ADVANCES_ACCOUNT_MISSING" }, "subject_type": { "type": "string" }, "subject_id": { "type": "string" }, "human_message": { "type": "string" }, "details": { "type": "array", "items": { "type": "string" } } }, "type": "object" } } }, "type": "object" }, "PaymentPayableRequestLine": { "required": [ "id", "payableId", "type", "amountPaid" ], "properties": { "id": { "type": "string", "format": "uuid" }, "payableId": { "description": "A purchases invoice (regular or opening) or a supplier debit note of the company (MER-3291), still named as an `invoice` payable. A missing or foreign document, or a supplier credit note (ADR 0216), answers 422 with `errors` naming this field.", "type": "string", "format": "uuid" }, "type": { "type": "string", "example": "invoice", "enum": [ "invoice" ] }, "amountPaid": { "description": "Number or decimal string, zero or more, with at most two decimals, in the currency of the invoice. It is what the payable applies when every method line counts its units in that currency, or when every line in another currency settles at an agreed settlement rate: then the debt the lines derive (units × agreed rate, or units ÷ agreed rate for money on the quote side, rounded half-up to two decimals) must equal what the payables apply, within a cent per agreed line when every invoice settles in full (422 derived_debt_does_not_match_applied_amounts), and the payment may settle several invoices. When a line converts at the official rate, the payment settles this one invoice and amountPaid is the debt its approver expects: the debt actually settled is derived from the units at the official rate of the day the payment is applied and stored as debt_settled. It may not exceed the invoice balance when the payment is created or edited (payment_exceeds_invoice_balance).", "oneOf": [ { "type": "number", "example": 70, "minimum": 0 }, { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,2})?$", "example": "70.00" } ] } }, "type": "object" }, "PaymentMethodRequestLine": { "required": [ "instrument_id", "amountPaid" ], "properties": { "instrument_id": { "description": "For advances, the instruments selected in the payment methods must be active, belong to the company and share one currency; USDT is refused. For settlements, an active payment instrument of the company, in any currency, whose treasury account is active (GET /treasury/payment-instruments/lookup). The line counts its amountPaid in the instrument's currency; in another currency than the invoices it converts at the official rate, which only USD and VES have (422 payment_currency_pair_not_supported otherwise), or at its agreed_rate. A missing or foreign one answers 404.", "type": "string", "format": "uuid" }, "amountPaid": { "description": "Number or decimal string, greater than zero, with at most two decimals. Its settling units (amountPaid − igtf_paid_amount) must derive at least one cent of the invoices' currency: a line at an agreed rate deriving less answers 422 payment_line_derives_no_debt with `errors` naming `methods.N.amountPaid` (MER-4384).", "oneOf": [ { "type": "number", "example": 60, "exclusiveMinimum": true, "minimum": 0 }, { "type": "string", "pattern": "^(?!0+(?:\\.0{1,2})?$)\\d+(?:\\.\\d{1,2})?$", "example": "60.00" } ] }, "reference": { "description": "An object of named keys; only named keys are stored and compared. Known keys: `email` (the provider's Binance Pay destination, exported for crypto wallet instruments), `reference` (the transfer reference) and `notes`. A JSON list, or a key that is a whole number written without leading zeros (such as `0`, `12` or `-3`), answers 422 with `errors` naming `methods.N.reference`; an empty `[]` reads as an empty object.", "type": "object", "example": { "email": "provider@example.com" }, "additionalProperties": true }, "agreed_rate": { "description": "Advances reject every non-null agreed_rate (422 advance_agreed_rate_not_supported). For settlements, optional. The Agreed Settlement Rate the line settles its invoices' debt at (MER-3125), quoted like the official pair (ADR 0208): USD per USDT against a USD debt, bolívares per USD or per USDT against a VES debt. Omitted, a USDT line takes the settlement terms of the provider all its invoices belong to (GET /providers/{id}/settlement-terms), with their declarer as responsible, and without terms it is refused (422 payment_agreed_settlement_rate_required); a USD/VES line converts at the official rate. Sent equal to the terms, the line follows them; any other rate is captured by whoever writes the payment, which needs backoffice.purchases.payments.agree-settlement-rate (403 payment_agreed_settlement_rate_not_permitted) and is audited. Sending the rate a pending payment stored keeps it. Refused on this field: a line in the invoices' currency (422 payment_agreed_settlement_rate_converts_nothing), a pair other than USDT, USD and VES (422 payment_currency_pair_not_supported). Once approved, a line's rate is frozen: an omitted rate matches a line without one or one following the terms.", "type": "string", "pattern": "^(?!0+\\.0+$)\\d{1,12}\\.\\d{1,8}$", "example": "1.02000000", "nullable": true }, "igtf_paid_amount": { "description": "Optional; omitted means 0.00 (backward compatible). The IGTF Paid the provider charges on this line (MER-2718, ADR 0193), counted in the line's currency, part of amountPaid. Zero or more, at most two decimals, lower than amountPaid (422 payment_igtf_paid_exceeds_cash on methods.N.igtf_paid_amount). Only amountPaid − igtf_paid_amount settles debt; the treasury leg moves the whole amountPaid. Applies to settlements and advances. Part of the line's terms: compared on an idempotent resend and frozen from approval.", "oneOf": [ { "type": "number", "example": 3.12, "minimum": 0 }, { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,2})?$", "example": "3.12" } ] } }, "type": "object" }, "PaymentLineAgreedSettlementRate": { "description": "The Agreed Settlement Rate the line settles at (MER-3125), known from the moment the payment is written; null when it converts nothing or at the official rate. Applying the payment copies it into the line's negotiated Rate Snapshot.", "required": [ "rate", "source", "agreed_by", "agreed_by_api_key_id" ], "properties": { "rate": { "type": "string", "example": "1.00000000" }, "source": { "description": "provider_terms: copied from the provider's settlement terms, whose declarer is its responsible; captured: agreed by whoever wrote the payment.", "type": "string", "enum": [ "provider_terms", "captured" ] }, "agreed_by": { "description": "The responsible user, or the owner of the API key.", "type": "string", "example": "12" }, "agreed_by_api_key_id": { "type": "string", "nullable": true } }, "type": "object", "nullable": true }, "PaymentMethodLine": { "required": [ "instrument", "amountPaid", "reference", "treasury_account_id", "treasury_account_name", "accounting_account_id", "accounting_account_code", "accounting_account_name", "currency", "agreed_settlement_rate", "igtf_paid_amount", "igtf_paid", "rate_snapshot", "treasury_relieved", "differences" ], "properties": { "instrument": { "description": "Null only on a line the purchase-contract automation created without finding its instrument. A name or class that no longer resolves is an empty string.", "required": [ "id", "name", "class" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "example": "Binance" }, "class": { "type": "string", "example": "crypto_wallet" } }, "type": "object", "nullable": true }, "amountPaid": { "description": "Units in the currency of the line's instrument.", "type": "string", "example": "60.00" }, "reference": { "description": "The named keys the line keeps. A line stored earlier with a list or whole-number keys reads back without them; an empty reference reads back as `[]`.", "type": "object", "example": { "email": "provider@example.com" }, "additionalProperties": true }, "treasury_account_id": { "description": "Null on history migrated onto an unlinked instrument and on a line still awaiting its snapshot.", "type": "string", "format": "uuid", "nullable": true }, "treasury_account_name": { "type": "string", "nullable": true }, "accounting_account_id": { "description": "The account the line posts to. Null while the line awaits its snapshot (purchase-contract automation).", "type": "string", "format": "uuid", "nullable": true }, "accounting_account_code": { "type": "string", "example": "1.1.02.", "nullable": true }, "accounting_account_name": { "type": "string", "example": "Binance", "nullable": true }, "currency": { "description": "The currency the line's units are counted in: its instrument's. Null only while the line awaits its snapshot.", "type": "string", "example": "VES", "nullable": true }, "agreed_settlement_rate": { "$ref": "#/components/schemas/PaymentLineAgreedSettlementRate" }, "igtf_paid_amount": { "description": "The IGTF Paid the provider charged on the line (MER-3686), in the line's currency; 0.00 when none.", "type": "string", "example": "3.12" }, "igtf_paid": { "description": "The IGTF Paid valued in each book when applied (fiat: the line's official rate; USDT: the per-unit value of the debt its settling units settle); posted to igtf_expense. Null before applying and on lines applied before MER-3686.", "required": [ "functional", "reporting", "functional_currency", "reporting_currency" ], "properties": { "functional": { "type": "string", "example": "405.60" }, "reporting": { "type": "string", "example": "3.12" }, "functional_currency": { "type": "string", "example": "VES" }, "reporting_currency": { "type": "string", "example": "USD" } }, "type": "object", "nullable": true }, "rate_snapshot": { "description": "The Rate Snapshot the line took when the payment was applied (ADR 0202); null before. Historical payments read an identity snapshot on the day they were applied.", "required": [ "currency", "rate", "rate_reference", "rate_rule", "rate_value_date", "rate_known_at", "rate_origin", "agreed_rate", "agreed_by", "agreed_by_api_key_id" ], "properties": { "currency": { "type": "string", "example": "VES" }, "rate": { "description": "The official USD/VES rate; 1.00000000 when nothing converts.", "type": "string", "example": "180.00000000" }, "rate_reference": { "description": "The official rate row; null for an identity valuation.", "type": "string", "nullable": true }, "rate_rule": { "type": "string", "enum": [ "identity", "publication_instant", "value_date", "negotiated" ] }, "rate_value_date": { "type": "string", "format": "date", "example": "2026-09-10" }, "rate_known_at": { "type": "string", "format": "date-time", "example": "2026-09-09T20:00:00+00:00", "nullable": true }, "rate_origin": { "type": "string", "nullable": true, "enum": [ "ingested", "manual" ] }, "agreed_rate": { "type": "string", "nullable": true }, "agreed_by": { "type": "string", "nullable": true }, "agreed_by_api_key_id": { "type": "string", "nullable": true } }, "type": "object", "nullable": true }, "treasury_relieved": { "description": "What the line's treasury leg posts in each book: the carrying amount it relieved plus the official value of what exceeded the position. Null before the payment is applied.", "required": [ "functional", "reporting", "functional_currency", "reporting_currency" ], "properties": { "functional": { "type": "string", "example": "5100.00" }, "reporting": { "type": "string", "example": "30.00" }, "functional_currency": { "type": "string", "example": "VES" }, "reporting_currency": { "type": "string", "example": "USD" } }, "type": "object", "nullable": true }, "differences": { "description": "The treasury-currency differences the line originated, per book (ADR 0199).", "type": "array", "items": { "$ref": "#/components/schemas/PaymentSettlementDifference" } } }, "type": "object" }, "PaymentMethodSnapshotLine": { "required": [ "instrument_id", "amountPaid", "reference", "treasury_account_id", "accounting_account_id", "currency", "agreed_settlement_rate", "igtf_paid_amount", "igtf_paid", "rate_snapshot", "treasury_relieved", "differences" ], "properties": { "instrument_id": { "type": "string", "format": "uuid", "nullable": true }, "amountPaid": { "description": "Units in the currency of the line's instrument.", "type": "string", "example": "60.00" }, "reference": { "description": "The named keys the line keeps. A line stored earlier with a list or whole-number keys reads back without them; an empty reference reads back as `[]`.", "type": "object", "additionalProperties": true }, "treasury_account_id": { "type": "string", "format": "uuid", "nullable": true }, "accounting_account_id": { "type": "string", "format": "uuid", "nullable": true }, "currency": { "description": "The currency the line's units are counted in: its instrument's. Null only while the line awaits its snapshot.", "type": "string", "example": "VES", "nullable": true }, "agreed_settlement_rate": { "$ref": "#/components/schemas/PaymentLineAgreedSettlementRate" }, "igtf_paid_amount": { "description": "The IGTF Paid the provider charged on the line (MER-3686), in the line's currency; 0.00 when none.", "type": "string", "example": "3.12" }, "igtf_paid": { "description": "The IGTF Paid valued in each book when applied (fiat: the line's official rate; USDT: the per-unit value of the debt its settling units settle); posted to igtf_expense. Null before applying and on lines applied before MER-3686.", "required": [ "functional", "reporting", "functional_currency", "reporting_currency" ], "properties": { "functional": { "type": "string", "example": "405.60" }, "reporting": { "type": "string", "example": "3.12" }, "functional_currency": { "type": "string", "example": "VES" }, "reporting_currency": { "type": "string", "example": "USD" } }, "type": "object", "nullable": true }, "rate_snapshot": { "description": "The Rate Snapshot the line took when the payment was applied (ADR 0202); null before. Historical payments read an identity snapshot on the day they were applied.", "required": [ "currency", "rate", "rate_reference", "rate_rule", "rate_value_date", "rate_known_at", "rate_origin", "agreed_rate", "agreed_by", "agreed_by_api_key_id" ], "properties": { "currency": { "type": "string", "example": "VES" }, "rate": { "description": "The official USD/VES rate; 1.00000000 when nothing converts.", "type": "string", "example": "180.00000000" }, "rate_reference": { "description": "The official rate row; null for an identity valuation.", "type": "string", "nullable": true }, "rate_rule": { "type": "string", "enum": [ "identity", "publication_instant", "value_date", "negotiated" ] }, "rate_value_date": { "type": "string", "format": "date", "example": "2026-09-10" }, "rate_known_at": { "type": "string", "format": "date-time", "example": "2026-09-09T20:00:00+00:00", "nullable": true }, "rate_origin": { "type": "string", "nullable": true, "enum": [ "ingested", "manual" ] }, "agreed_rate": { "type": "string", "nullable": true }, "agreed_by": { "type": "string", "nullable": true }, "agreed_by_api_key_id": { "type": "string", "nullable": true } }, "type": "object", "nullable": true }, "treasury_relieved": { "description": "What the line's treasury leg posts in each book: the carrying amount it relieved plus the official value of what exceeded the position. Null before the payment is applied.", "required": [ "functional", "reporting", "functional_currency", "reporting_currency" ], "properties": { "functional": { "type": "string", "example": "5100.00" }, "reporting": { "type": "string", "example": "30.00" }, "functional_currency": { "type": "string", "example": "VES" }, "reporting_currency": { "type": "string", "example": "USD" } }, "type": "object", "nullable": true }, "differences": { "description": "The treasury-currency differences the line originated, per book (ADR 0199).", "type": "array", "items": { "$ref": "#/components/schemas/PaymentSettlementDifference" } } }, "type": "object" }, "PaymentSettlementDifference": { "description": "One per-book settlement difference, signed from the company's side: positive is a gain, negative a loss (ADR 0199).", "required": [ "cause", "book", "amount", "currency" ], "properties": { "cause": { "type": "string", "enum": [ "debt_currency", "treasury_currency", "agreed_rate", "rounding" ] }, "book": { "type": "string", "enum": [ "functional", "reporting" ] }, "amount": { "type": "string", "example": "-1.67" }, "currency": { "type": "string", "example": "USD" } }, "type": "object" }, "PaymentPayableLine": { "required": [ "id", "payable_id", "type", "amount_paid", "relieved_document", "relieved_functional", "relieved_reporting", "document_currency", "debt_settled", "relieved", "differences" ], "properties": { "id": { "type": "string", "format": "uuid" }, "payable_id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "example": "invoice", "enum": [ "invoice" ] }, "amount_paid": { "type": "string", "example": "5100.00" }, "relieved_document": { "description": "Kept for compatibility: `relieved.document`.", "type": "string", "example": "5100.00", "nullable": true }, "relieved_functional": { "description": "Kept for compatibility: `relieved.functional`.", "type": "string", "example": "5100.00", "nullable": true }, "relieved_reporting": { "description": "Kept for compatibility: `relieved.reporting`.", "type": "string", "example": "30.00", "nullable": true }, "document_currency": { "description": "The invoice currency of `debt_settled` and `relieved.document`; null before the payment is applied.", "type": "string", "example": "VES", "nullable": true }, "debt_settled": { "description": "The Debt Settlement Amount; null before the payment is applied. Historical payments read their amount paid.", "type": "string", "example": "5100.00", "nullable": true }, "relieved": { "description": "The three amounts the payable relieved from its invoice, each with its currency (ADR 0122); a cancellation gives exactly these back. Null when none was recorded.", "required": [ "document", "functional", "reporting", "document_currency", "functional_currency", "reporting_currency" ], "properties": { "document": { "type": "string", "example": "5100.00" }, "functional": { "type": "string", "example": "5100.00" }, "reporting": { "type": "string", "example": "30.00" }, "document_currency": { "type": "string", "example": "VES" }, "functional_currency": { "type": "string", "example": "VES" }, "reporting_currency": { "type": "string", "example": "USD" } }, "type": "object", "nullable": true }, "differences": { "description": "The debt-currency, agreed-rate and rounding differences the payable originated, per book (ADR 0199).", "type": "array", "items": { "$ref": "#/components/schemas/PaymentSettlementDifference" } } }, "type": "object" }, "PaymentCreateResult": { "description": "The payment a create answers with: the one it created, or the one already stored under the id, as it stands now.", "required": [ "id", "code", "status" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string", "example": "PGO00001" }, "status": { "type": "string", "example": "to_be_approved", "enum": [ "to_be_approved", "to_be_applied", "applied", "cancelled" ] } }, "type": "object" }, "PaymentApplyResult": { "description": "The payment an application answers with, applied now or before.", "required": [ "id", "status", "date_payment_applied" ], "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "example": "applied", "enum": [ "applied" ] }, "date_payment_applied": { "description": "The date the payment was applied on, as stored.", "type": "string", "format": "date", "example": "2026-09-29", "nullable": true } }, "type": "object" }, "ProviderProblem": { "description": "The controller's Problem. A domain refusal carries its error_code and null errors; a validation refusal has a null error_code and errors mapping each field to its messages.", "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string", "example": "Not Found" }, "status": { "type": "integer", "example": 404 }, "detail": { "type": "string" }, "error_code": { "type": "string", "example": "company_not_found", "nullable": true }, "errors": { "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" }, "ProviderMiddlewareError": { "description": "Authentication, tenant and API-key middleware answer with message instead of the controller Problem; an unknown tenant is 404 with message Recurso no encontrado.", "required": [ "message" ], "properties": { "message": { "type": "string" } }, "type": "object" }, "ProviderSettlementTermRequestLine": { "required": [ "payment_currency", "settled_currency", "agreed_rate" ], "properties": { "payment_currency": { "description": "The currency the provider is paid in. Only USDT, the one currency without an official rate, has terms; a known currency outside the pair answers 422 provider_settlement_terms_pair_not_supported and an unknown one 422 invalid_currency, both naming the field.", "type": "string", "example": "USDT", "maxLength": 4, "minLength": 3, "enum": [ "USDT" ] }, "settled_currency": { "description": "The currency of the debt the money settles, which the rate quotes against.", "type": "string", "example": "USD", "maxLength": 4, "minLength": 3, "enum": [ "USD", "VES" ] }, "agreed_rate": { "description": "Greater than zero, with one to eight decimals, quoted like the official pair (ADR 0208): USD per USDT against a USD debt (1 USDT settles USD 1 is 1.00000000), bolívares per USDT against a VES debt.", "type": "string", "pattern": "^(?!0+\\.0+$)\\d{1,12}\\.\\d{1,8}$", "example": "1.00000000" } }, "type": "object", "additionalProperties": false }, "ProviderSettlementTerm": { "required": [ "payment_currency", "settled_currency", "agreed_rate", "declared_by", "declared_by_api_key_id", "declared_at" ], "properties": { "payment_currency": { "type": "string", "example": "USDT" }, "settled_currency": { "type": "string", "example": "USD", "enum": [ "USD", "VES" ] }, "agreed_rate": { "description": "Eight decimals.", "type": "string", "example": "1.00000000" }, "declared_by": { "description": "The user who declared the term, or the owner of the API key it was declared through.", "type": "string", "example": "12" }, "declared_by_api_key_id": { "description": "The API key the term was declared through, or null when a user declared it in the app.", "type": "string", "example": null, "nullable": true }, "declared_at": { "description": "UTC. A term redeclared at the same rate keeps its declarer and instant.", "type": "string", "format": "date-time", "example": "2026-09-30T14:00:00+00:00" } }, "type": "object" }, "ProviderSettlementTermsView": { "required": [ "provider_id", "terms" ], "properties": { "provider_id": { "type": "string", "format": "uuid" }, "terms": { "description": "One per pair, ordered by payment and settled currency; empty when the provider has none.", "type": "array", "items": { "$ref": "#/components/schemas/ProviderSettlementTerm" } } }, "type": "object" }, "PurchaseOrderProblem": { "description": "Controller validation and domain errors for purchase orders. Validation has a null error_code and an errors object mapping field names to messages. A domain refusal has an error_code; its errors is null, except `purchase_line_item_mismatch`, whose errors names each refused line field (items.N.category_id, items.N.unit_id), and `purchases_provider_inactive` / `purchases_provider_not_found`, whose errors names `provider_id`.", "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "error_code": { "type": "string", "nullable": true }, "errors": { "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" }, "PurchaseOrderEmailNotVerified": { "description": "The `verified` middleware, answered before the controller runs.", "required": [ "message" ], "properties": { "message": { "type": "string" }, "status": { "type": "string", "example": "email_not_verified" }, "detail": { "type": "string" } }, "type": "object" }, "PurchasesInvoiceLiveNote": { "description": "A note of the purchases invoice that is not cancelled, draft included.", "required": [ "id", "code", "kind", "status" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string", "example": "NCP2600001" }, "kind": { "type": "string", "enum": [ "credit_note", "debit_note" ] }, "status": { "description": "to_be_approved, with_supplier_credit or applied for a credit note; render an unknown value generically.", "type": "string", "example": "to_be_approved" } }, "type": "object" }, "PurchasesInvoiceNote": { "description": "A Supplier Credit or Debit Note of the invoice as its detail shows it (MER-3292).", "required": [ "id", "code", "kind", "status", "emission_date", "registration_date", "currency", "total", "balance", "applied_to_invoice" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string", "example": "NCP2600001" }, "kind": { "type": "string", "enum": [ "credit_note", "debit_note" ] }, "status": { "description": "A credit note: to_be_approved, with_supplier_credit, applied or cancelled. A debit note: to_be_approved, to_be_paid, partially_paid, fully_paid or cancelled.", "type": "string", "example": "with_supplier_credit", "enum": [ "to_be_approved", "with_supplier_credit", "applied", "to_be_paid", "partially_paid", "fully_paid", "cancelled" ] }, "emission_date": { "type": "string", "format": "date", "example": "2026-09-29" }, "registration_date": { "description": "The day the Company booked the note (ADR 0157).", "type": "string", "format": "date", "example": "2026-09-29" }, "currency": { "description": "The invoice's Document Currency, which the note inherits.", "type": "string", "example": "USD", "enum": [ "USD", "VES" ] }, "total": { "type": "string", "example": "60.00" }, "balance": { "description": "The note's Open Balance: what a debit note still owes, or the Supplier Credit a credit note keeps. 0.00 for a draft or a cancelled note.", "type": "string", "example": "10.00" }, "applied_to_invoice": { "description": "A credit note: what its active Supplier Credit Applications relieved from this invoice, 0.00 for a draft, a cancelled note or a note approved while the invoice owed nothing. Null for a debit note.", "type": "string", "example": "50.00", "nullable": true } }, "type": "object" }, "VatWithholdingProposal": { "description": "What the proposed rule would withhold from the VAT of a purchase still to be approved, approved now (MER-3107): the standard rule, or, when the provider's current VAT Taxpayer Type is `formal`, the art. 3 n. 2 exclusion `art3_n2_supplier_formal_taxpayer` at 0 %, since a formal taxpayer is never withheld from and admits only an art. 3 exclusion (MER-5392; before MER-5392 a formal provider was proposed, wrongly, the standard rule). Null when the invoice is approved, its company withholds no VAT or cannot tell yet (no Fiscal Profile, no tax attributes or no proposed rule in force on the registration date), the invoice charges no VAT, or no rate values it today.", "required": [ "rule_id", "rule_code", "rule_kind", "rule_label", "percentage", "vat_base_ves", "withheld_amount_ves", "relief_document", "exclusion_required", "suggested_reason_note" ], "properties": { "rule_id": { "description": "The VAT withholding rule the withholding would snapshot.", "type": "string", "format": "uuid" }, "rule_code": { "type": "string", "example": "standard" }, "rule_kind": { "description": "The kind of the proposed rule, as the catalog names it: the standard rate, an art. 5 cause (full) or an art. 3 exclusion.", "type": "string", "example": "standard", "enum": [ "standard", "full", "exclusion" ] }, "rule_label": { "description": "The catalog label of the proposed rule, so the approval can name it without reading the catalog.", "type": "string", "example": "Retención general del 75 % del IVA causado" }, "percentage": { "description": "The share of the VAT withheld, a decimal string.", "type": "string", "example": "75.00" }, "vat_base_ves": { "description": "The VAT charged, in bolívars.", "type": "string", "example": "2080.00" }, "withheld_amount_ves": { "description": "The legal amount withheld, in bolívars.", "type": "string", "example": "1560.00" }, "relief_document": { "description": "What the supplier's debt would give up, in the invoice's Document Currency.", "required": [ "amount", "currency" ], "properties": { "amount": { "type": "string", "example": "12.00" }, "currency": { "type": "string", "example": "USD" } }, "type": "object" }, "exclusion_required": { "description": "True when the provider is a formal VAT taxpayer: the approval accepts only an art. 3 exclusion, and the standard rule and the art. 5 causes are refused with VAT_WITHHOLDING_EXCLUSION_REQUIRED (MER-5392). Never null.", "type": "boolean", "example": false }, "suggested_reason_note": { "description": "Evidence the exclusion's supporting note may start from; non-null only when `exclusion_required`.", "type": "string", "example": null, "nullable": true } }, "type": "object", "nullable": true }, "ClientCustomerCredit": { "description": "A client's Customer Credit in one currency, with the credit notes that generate it (MER-3178).", "required": [ "currency", "amount", "credit_notes" ], "properties": { "currency": { "type": "string", "example": "USD", "enum": [ "USD", "VES" ] }, "amount": { "description": "The sum of the balances of the client's credit notes with_customer_credit in this currency.", "type": "string", "example": "6.60" }, "credit_notes": { "description": "By emission date, then code. [] when the caller lacks backoffice.sales.credit-notes.view; the amount stays.", "type": "array", "items": { "required": [ "id", "code", "balance" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string", "example": "NC2600001" }, "balance": { "description": "The Customer Credit this note keeps.", "type": "string", "example": "6.60" } }, "type": "object" } } }, "type": "object" }, "ClientFiscalIdentitySnake": { "required": [ "document_type", "document_number", "legal_name", "fiscal_address", "phone", "email", "vat_taxpayer_type", "special_taxpayer_since", "islr_person_type", "vat_withholding_agent", "islr_withholding_agent", "complete", "missing" ], "properties": { "document_type": { "type": "string", "nullable": true }, "document_number": { "type": "string", "nullable": true }, "legal_name": { "type": "string", "nullable": true }, "fiscal_address": { "type": "string", "nullable": true }, "phone": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true }, "vat_taxpayer_type": { "type": "string", "nullable": true }, "special_taxpayer_since": { "type": "string", "format": "date", "nullable": true }, "vat_withholding_agent": { "description": "Declared client VAT withholding-agent designation; independent of Special Taxpayer. Omission defaults false on create and preserves the current value on update.", "type": "boolean" }, "islr_withholding_agent": { "description": "Declared client ISLR withholding-agent designation; independent of VAT designation. Omission defaults false on create and preserves the current value on update.", "type": "boolean" }, "islr_person_type": { "type": "string", "nullable": true }, "complete": { "type": "boolean" }, "missing": { "type": "array", "items": { "type": "string" } } }, "type": "object" }, "ClientFiscalIdentityInput": { "properties": { "document_type": { "type": "string", "nullable": true }, "document_number": { "type": "string", "nullable": true }, "legal_name": { "type": "string", "nullable": true }, "fiscal_address": { "type": "string", "nullable": true }, "phone": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true }, "vat_taxpayer_type": { "type": "string", "nullable": true }, "special_taxpayer_since": { "type": "string", "format": "date", "nullable": true }, "vat_withholding_agent": { "description": "Declared client VAT withholding-agent designation; independent of Special Taxpayer. Omission defaults false on create and preserves the current value on update.", "type": "boolean" }, "islr_withholding_agent": { "description": "Declared client ISLR withholding-agent designation; independent of VAT designation. Omission defaults false on create and preserves the current value on update.", "type": "boolean" }, "islr_person_type": { "type": "string", "nullable": true } }, "type": "object", "nullable": true }, "ClientLabel": { "required": [ "id", "name", "tone", "archived" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "tone": { "type": "string" }, "archived": { "type": "boolean" } }, "type": "object" }, "ClientListItem": { "required": [ "id", "code", "name", "description", "status", "company_id", "fiscal_identity", "labels", "default_payment_term" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "default_payment_term": { "type": "string", "nullable": true, "enum": [ "cash", "five_days", "seven_days", "fifteen_days", "thirty_days" ] }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "status": { "description": "Known states active and inactive; legacy unknown states remain readable.", "type": "string" }, "company_id": { "type": "string", "format": "uuid" }, "default_price_list_id": { "type": "string", "format": "uuid", "nullable": true }, "fiscal_identity": { "$ref": "#/components/schemas/ClientFiscalIdentitySnake" }, "labels": { "type": "array", "items": { "$ref": "#/components/schemas/ClientLabel" } } }, "type": "object" }, "ClientDetail": { "required": [ "id", "code", "name", "description", "status", "company_id", "fiscal_identity", "customer_credit", "labels", "default_payment_term" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "default_payment_term": { "type": "string", "nullable": true, "enum": [ "cash", "five_days", "seven_days", "fifteen_days", "thirty_days" ] }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "status": { "description": "Known states active and inactive; legacy unknown states remain readable.", "type": "string" }, "company_id": { "type": "string", "format": "uuid" }, "default_price_list_id": { "type": "string", "format": "uuid", "nullable": true }, "fiscal_identity": { "$ref": "#/components/schemas/ClientFiscalIdentitySnake" }, "customer_credit": { "description": "One entry per currency; [] when the client keeps no Customer Credit.", "type": "array", "items": { "$ref": "#/components/schemas/ClientCustomerCredit" } }, "labels": { "type": "array", "items": { "$ref": "#/components/schemas/ClientLabel" } } }, "type": "object" }, "ClientListMeta": { "required": [ "counts", "label_counts" ], "properties": { "counts": { "required": [ "active", "inactive" ], "properties": { "active": { "type": "integer" }, "inactive": { "type": "integer" } }, "type": "object", "additionalProperties": { "type": "integer" } }, "label_counts": { "type": "object", "additionalProperties": { "type": "integer" } } }, "type": "object" }, "ClientListResponse": { "required": [ "items", "total", "per_page", "current_page", "meta" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ClientListItem" } }, "total": { "type": "integer" }, "per_page": { "type": "integer" }, "current_page": { "type": "integer" }, "meta": { "$ref": "#/components/schemas/ClientListMeta" } }, "type": "object" }, "ClientProblem": { "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "error_code": { "type": "string", "nullable": true }, "errors": { "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" }, "ClientValidationProblem": { "description": "Laravel validation through ApiController: errors keyed by field path.", "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "error_code": { "type": "string", "nullable": true }, "errors": { "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" }, "ClientDocumentConflict": { "required": [ "title", "status", "detail", "error_code", "errors", "existing_code" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "error_code": { "type": "string", "nullable": true }, "errors": { "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "existing_code": { "type": "string" } }, "type": "object" }, "ClientMiddlewareMessage": { "required": [ "message" ], "properties": { "message": { "type": "string" } }, "type": "object" }, "ClientMiddlewareForbidden": { "required": [ "title", "status", "detail" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" } }, "type": "object" }, "ClientRequestValidation": { "required": [ "message", "errors" ], "properties": { "message": { "type": "string" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" }, "ClientComment": { "required": [ "id", "body", "author_user_id", "created_at", "updated_at", "edited_at", "can_edit", "can_delete", "mentions" ], "properties": { "id": { "type": "string", "format": "uuid" }, "body": { "type": "string" }, "author_user_id": { "type": "integer" }, "mentions": { "type": "array", "items": { "required": [ "user_id", "name" ], "properties": { "user_id": { "type": "integer" }, "name": { "type": "string" } }, "type": "object" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "edited_at": { "type": "string", "format": "date-time", "nullable": true }, "parent_id": { "type": "string", "format": "uuid", "nullable": true }, "is_deleted": { "type": "boolean" }, "can_edit": { "type": "boolean" }, "can_delete": { "type": "boolean" } }, "type": "object" }, "ClientAttachment": { "required": [ "id", "original_name", "mime_type", "size_bytes", "uploaded_by", "created_at", "comment_id", "can_delete" ], "properties": { "id": { "type": "string", "format": "uuid" }, "original_name": { "type": "string" }, "mime_type": { "type": "string" }, "size_bytes": { "type": "integer" }, "uploaded_by": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "comment_id": { "type": "string", "format": "uuid", "nullable": true }, "can_delete": { "type": "boolean" } }, "type": "object" }, "CollectionDocument": { "required": [ "id", "code", "customer_id", "emission_date", "status", "total", "balance", "currency", "kind" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "customer_id": { "type": "string", "format": "uuid" }, "emission_date": { "type": "string", "format": "date" }, "status": { "type": "string" }, "total": { "type": "string" }, "balance": { "type": "string" }, "currency": { "type": "string" }, "kind": { "type": "string", "enum": [ "regular", "opening", "debit_note" ] } }, "type": "object" }, "CollectionRateSnapshot": { "description": "Frozen valuation selected at registration; absent on non-inferable legacy history.", "required": [ "currency", "rate", "rate_reference", "rate_rule", "rate_value_date", "rate_known_at", "rate_origin", "agreed_rate", "agreed_by", "agreed_by_api_key_id" ], "properties": { "currency": { "type": "string" }, "rate": { "type": "string" }, "rate_reference": { "type": "string", "nullable": true }, "rate_rule": { "type": "string" }, "rate_value_date": { "type": "string", "format": "date" }, "rate_known_at": { "type": "string", "format": "date-time", "nullable": true }, "rate_origin": { "type": "string", "nullable": true }, "agreed_rate": { "type": "string", "nullable": true }, "agreed_by": { "type": "string", "nullable": true }, "agreed_by_api_key_id": { "type": "string", "nullable": true } }, "type": "object", "nullable": true }, "CollectionAgreedSettlementRatePair": { "description": "Direction of the frozen agreed rate, derived exclusively from positive frozen applications. USD/VES quotes VES per USD; USDT/USD or USDT/VES quotes document currency per USDT. Null for official lines or insufficient legacy evidence.", "required": [ "base_currency", "quote_currency" ], "properties": { "base_currency": { "type": "string", "enum": [ "USD", "USDT" ] }, "quote_currency": { "type": "string", "enum": [ "USD", "VES" ] } }, "type": "object", "nullable": true }, "CollectionTreasuryRelieved": { "required": [ "functional", "reporting", "functional_currency", "reporting_currency" ], "properties": { "functional": { "type": "string" }, "reporting": { "type": "string" }, "functional_currency": { "type": "string" }, "reporting_currency": { "type": "string" } }, "type": "object", "nullable": true }, "CollectionPerceivedIgtf": { "description": "The IGTF classification frozen on the line at registration (MER-3687, ADR 0193). Null when not evaluated: a company without a Fiscal Profile, a refund, or a line registered before MER-3687. A later IGTF rate never changes it.", "required": [ "outcome", "reason", "numeral", "rule_id", "percentage", "base", "amount", "value", "operates_outside_national_banking" ], "properties": { "outcome": { "type": "string", "enum": [ "not_perceived", "perceived" ] }, "reason": { "description": "Why a line was not perceived; null when perceived.", "type": "string", "nullable": true, "enum": [ "legal_tender_currency", "financial_system_intermediated", "company_not_perception_agent" ] }, "numeral": { "description": "The art. 4 numeral the perceived rate belongs to.", "type": "integer", "example": 6, "nullable": true }, "rule_id": { "description": "The IGTF rates catalog row applied.", "type": "string", "format": "uuid", "nullable": true }, "percentage": { "type": "string", "example": "3.00", "nullable": true }, "base": { "description": "Line currency: amountCollected ÷ (1 + rate), rounded once half-up; what settles debt.", "type": "string", "example": "60.00", "nullable": true }, "amount": { "description": "The IGTF in the line currency: amountCollected − base.", "type": "string", "example": "1.80", "nullable": true }, "value": { "$ref": "#/components/schemas/CollectionPerceivedIgtfValue" }, "operates_outside_national_banking": { "description": "Whether the line's instrument operated outside the national banking system when the line was registered.", "type": "boolean" } }, "type": "object", "nullable": true }, "CollectionPerceivedIgtfValue": { "description": "The IGTF valued per book when applied: fiat at the line's official rate, USDT by the debt its settling units settle (ADR 0200); credited to igtf_payable. Null unless perceived.", "required": [ "functional", "reporting", "functional_currency", "reporting_currency" ], "properties": { "functional": { "type": "string", "example": "208.80" }, "reporting": { "type": "string", "example": "1.74" }, "functional_currency": { "type": "string", "example": "VES" }, "reporting_currency": { "type": "string", "example": "USD" } }, "type": "object", "nullable": true }, "CollectionRelievedAmounts": { "description": "Null on pre-MER-2955 history and inert zero applications.", "required": [ "document", "functional", "reporting", "document_currency", "functional_currency", "reporting_currency" ], "properties": { "document": { "type": "string" }, "functional": { "type": "string" }, "reporting": { "type": "string" }, "document_currency": { "type": "string" }, "functional_currency": { "type": "string" }, "reporting_currency": { "type": "string" } }, "type": "object", "nullable": true }, "CollectionDebtSettled": { "description": "Null on inert zero applications or legacy data without inferable debt.", "required": [ "amount", "currency" ], "properties": { "amount": { "type": "string" }, "currency": { "type": "string" } }, "type": "object", "nullable": true }, "CollectionSettlementDifference": { "required": [ "cause", "book", "amount", "currency", "origin_type", "origin_key" ], "properties": { "cause": { "type": "string" }, "book": { "type": "string" }, "amount": { "type": "string" }, "currency": { "type": "string" }, "origin_type": { "type": "string" }, "origin_key": { "type": "string" } }, "type": "object" }, "CollectionCollectableDetail": { "required": [ "id", "collectableId", "type", "amountCollected", "code", "currency", "status", "kind", "debt_settled", "relieved", "differences" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "description": "The collected document's internal code, read at request time; null exactly when kind is null.", "type": "string", "nullable": true }, "currency": { "description": "Current invoice currency, descriptive only; recorded financial currency remains in debt_settled and relieved.", "type": "string", "nullable": true }, "kind": { "description": "The kind of the document the line collects, read at request time (MER-3350); route on it, never on type, which is invoice for every kind. regular and opening are read at GET /sales/sales-invoices/{id}, debit_note at GET /sales/debit-notes/{id}. A collection never collects a credit note, so credit_note is never returned here. Null when the document is missing or belongs to another company: read no document then.", "type": "string", "nullable": true, "enum": [ "regular", "opening", "credit_note", "debit_note" ] }, "status": { "type": "string", "nullable": true }, "collectableId": { "type": "string", "format": "uuid" }, "type": { "type": "string" }, "amountCollected": { "type": "string" }, "debt_settled": { "$ref": "#/components/schemas/CollectionDebtSettled" }, "relieved": { "$ref": "#/components/schemas/CollectionRelievedAmounts" }, "differences": { "type": "array", "items": { "$ref": "#/components/schemas/CollectionSettlementDifference" } } }, "type": "object" }, "CollectionInvoiceDisplay": { "required": [ "id", "code", "currency", "status", "kind" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "description": "The collected document's internal code, read at request time; null exactly when kind is null.", "type": "string", "nullable": true }, "currency": { "type": "string", "nullable": true }, "kind": { "description": "The kind of the collected document, read at request time: regular, opening or debit_note; never credit_note. Null when the document is missing or belongs to another company.", "type": "string", "nullable": true, "enum": [ "regular", "opening", "credit_note", "debit_note" ] }, "status": { "type": "string", "nullable": true } }, "type": "object" }, "CollectionLabel": { "required": [ "id", "name", "tone", "archived" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "tone": { "type": "string" }, "archived": { "type": "boolean" } }, "type": "object" }, "CollectionValidationProblem": { "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string" }, "error_code": { "type": "string", "nullable": true }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" }, "ContactIdentityRequest": { "required": [ "phone" ], "properties": { "phone": { "type": "string" } }, "type": "object", "additionalProperties": false }, "ContactEvidence": { "required": [ "inbound_event_id", "occurred_at", "channel" ], "properties": { "inbound_event_id": { "type": "string", "maxLength": 200, "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "channel": { "type": "string", "enum": [ "WHATSAPP" ] } }, "type": "object", "additionalProperties": false }, "ContactCaptureRequest": { "required": [ "phone", "evidence" ], "properties": { "phone": { "type": "string" }, "evidence": { "$ref": "#/components/schemas/ContactEvidence" } }, "type": "object", "additionalProperties": false }, "ContactEntry": { "required": [ "value", "kind" ], "properties": { "field": { "type": "string", "enum": [ "name", "phone_kind", "email", "email_kind", "business_name", "decision_maker", "source", "notes" ] }, "topic": { "type": "string", "maxLength": 80, "minLength": 1 }, "value": { "description": "Core reported fields stop at 255 Unicode characters; notes and topics stop at 4000. Email must be valid. Contact kinds are WORK PERSONAL OTHER. Native null clears; linked required core cannot be cleared.", "type": "string", "nullable": true, "maxLength": 4000, "minLength": 1 }, "kind": { "type": "string", "enum": [ "REPORTED", "HYPOTHESIS", "TO_VERIFY" ] } }, "type": "object", "oneOf": [ { "required": [ "field" ] }, { "required": [ "topic" ] } ], "additionalProperties": false }, "ContactEnrichRequest": { "required": [ "expected_version", "entries", "evidence" ], "properties": { "expected_version": { "type": "integer", "minimum": 1 }, "entries": { "type": "array", "items": { "$ref": "#/components/schemas/ContactEntry" }, "maxItems": 20, "minItems": 1 }, "evidence": { "$ref": "#/components/schemas/ContactEvidence" } }, "type": "object", "additionalProperties": false }, "ContactView": { "required": [ "id", "phone", "version", "provenance" ], "properties": { "id": { "type": "string", "format": "uuid" }, "phone": { "type": "string" }, "version": { "type": "integer", "minimum": 1 }, "name": { "type": "string", "nullable": true }, "phone_kind": { "type": "string", "nullable": true, "enum": [ "WORK", "PERSONAL", "OTHER" ] }, "email": { "type": "string", "nullable": true }, "email_kind": { "type": "string", "nullable": true, "enum": [ "WORK", "PERSONAL", "OTHER" ] }, "business_name": { "type": "string", "nullable": true }, "decision_maker": { "type": "string", "nullable": true }, "source": { "type": "string", "nullable": true }, "notes": { "type": "string", "nullable": true }, "legacy_potential_customer_id": { "type": "string", "format": "uuid", "nullable": true }, "legacy_attribution": { "type": "string", "nullable": true, "enum": [ "LEGACY_UNATTRIBUTED" ] }, "provenance_has_more": { "type": "boolean" }, "field_provenance": { "type": "object", "additionalProperties": true }, "provenance": { "type": "array", "items": { "properties": { "field": { "type": "string" }, "topic": { "type": "string" }, "value": { "type": "string", "nullable": true }, "kind": { "type": "string", "enum": [ "REPORTED", "HYPOTHESIS", "TO_VERIFY" ] }, "source_channel": { "type": "string" }, "source_event": { "type": "string" }, "observed_at": { "type": "string", "format": "date-time" }, "recorded_at": { "type": "string", "format": "date-time" }, "actor": { "type": "string" }, "effect_id": { "type": "string", "format": "uuid" } }, "type": "object" } } }, "type": "object" }, "ContactIdentityResult": { "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "ABSENT", "FOUND", "AMBIGUOUS" ] }, "contact": { "$ref": "#/components/schemas/ContactView" }, "match_count": { "type": "integer", "minimum": 2 } }, "type": "object" }, "ContactEffect": { "required": [ "effect_id", "request_hash", "state", "original_result", "failure_code", "http_status" ], "properties": { "effect_id": { "type": "string", "format": "uuid" }, "request_hash": { "type": "string", "maxLength": 64, "minLength": 64 }, "state": { "type": "string", "enum": [ "PENDING", "APPLIED", "FAILED" ] }, "original_result": { "properties": { "contact": { "$ref": "#/components/schemas/ContactView" }, "created": { "type": "boolean" } }, "type": "object", "nullable": true }, "failure_code": { "type": "string", "nullable": true }, "http_status": { "type": "integer", "nullable": true } }, "type": "object" }, "ContactProblem": { "required": [ "title", "status", "detail", "error_code" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "error_code": { "type": "string", "nullable": true }, "errors": { "type": "object", "nullable": true } }, "type": "object" }, "ContactRestrictionBody": { "required": [ "reason", "evidence" ], "properties": { "reason": { "type": "string", "enum": [ "CUSTOMER_REQUESTED_OPT_OUT" ] }, "evidence": { "$ref": "#/components/schemas/ContactEvidence" } }, "type": "object", "additionalProperties": false }, "ContactRestrictionView": { "required": [ "contact_id", "status", "reason", "effect_id", "restricted_at", "purchase_preserved", "data_deletion_requested", "cancel_purchase_requested", "next_action", "follow_ups_executable" ], "properties": { "contact_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "NONE", "ACTIVE" ] }, "reason": { "type": "string", "nullable": true, "enum": [ "CUSTOMER_REQUESTED_OPT_OUT" ] }, "effect_id": { "type": "string", "format": "uuid", "nullable": true }, "restricted_at": { "type": "string", "format": "date-time", "nullable": true }, "purchase_preserved": { "type": "boolean" }, "data_deletion_requested": { "type": "boolean" }, "cancel_purchase_requested": { "type": "boolean" }, "next_action": { "type": "string", "enum": [ "NONE" ] }, "follow_ups_executable": { "type": "boolean" } }, "type": "object" }, "ContactRestrictionEffect": { "required": [ "effect_id", "request_hash", "state", "original_result", "failure_code", "http_status" ], "properties": { "effect_id": { "type": "string", "format": "uuid" }, "request_hash": { "type": "string", "maxLength": 64, "minLength": 64 }, "state": { "type": "string", "enum": [ "PENDING", "APPLIED", "FAILED" ] }, "original_result": { "properties": { "restriction": { "$ref": "#/components/schemas/ContactRestrictionView" }, "created": { "type": "boolean" } }, "type": "object", "nullable": true }, "failure_code": { "type": "string", "nullable": true }, "http_status": { "type": "integer", "nullable": true } }, "type": "object" }, "ContractSourceLine": { "required": [ "id", "category_id", "item_id", "item_name", "quantity", "tariff_period", "agreed_rate", "subtotal", "tax_id", "tax_percentage", "discount_percentage", "accounting_account_id", "accounting_center_id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "category_id": { "type": "string", "format": "uuid" }, "item_id": { "type": "string", "format": "uuid" }, "item_name": { "type": "string" }, "quantity": { "type": "string" }, "tariff_period": { "type": "string" }, "agreed_rate": { "type": "string" }, "subtotal": { "type": "string" }, "tax_id": { "type": "string", "format": "uuid" }, "tax_percentage": { "type": "string" }, "discount_percentage": { "type": "string" }, "accounting_account_id": { "type": "string", "format": "uuid" }, "accounting_center_id": { "type": "string", "format": "uuid" } }, "type": "object" }, "ActivationSourceLine": { "required": [ "id", "category_id", "item_id", "item_name", "quantity", "tariff_period", "agreed_rate", "subtotal", "tax_id", "tax_percentage", "discount_percentage", "accounting_account_id", "accounting_center_id", "contract_item_id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "category_id": { "type": "string", "format": "uuid" }, "item_id": { "type": "string", "format": "uuid" }, "item_name": { "type": "string" }, "quantity": { "type": "string" }, "tariff_period": { "type": "string" }, "agreed_rate": { "type": "string" }, "subtotal": { "type": "string" }, "tax_id": { "type": "string", "format": "uuid" }, "tax_percentage": { "type": "string" }, "discount_percentage": { "type": "string" }, "accounting_account_id": { "type": "string", "format": "uuid" }, "accounting_center_id": { "type": "string", "format": "uuid" }, "contract_item_id": { "type": "string", "format": "uuid" } }, "type": "object" }, "ActivationContractSource": { "required": [ "id", "code", "company_id", "client_id", "status", "start_date", "due_date", "items", "subtotal", "discount", "taxes", "total" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "company_id": { "type": "string", "format": "uuid" }, "client_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "start_date": { "type": "string", "format": "date" }, "due_date": { "type": "string", "format": "date" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/ContractSourceLine" } }, "subtotal": { "type": "string" }, "discount": { "type": "string" }, "taxes": { "type": "string" }, "total": { "type": "string" } }, "type": "object" }, "ContractActivationWriteItem": { "required": [ "id", "contract_item_id", "category_id", "item_id", "item_name", "quantity", "tariff_period", "tax_id", "tax_percentage", "discount_percentage", "accounting_account_id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "contract_item_id": { "type": "string", "format": "uuid" }, "category_id": { "type": "string", "format": "uuid" }, "item_id": { "type": "string", "format": "uuid" }, "item_name": { "type": "string", "maxLength": 255 }, "quantity": { "type": "string", "pattern": "^\\\\d+(\\\\.\\\\d{1,4})?$", "example": "1.0000" }, "tariff_period": { "type": "string", "enum": [ "semi_monthly", "monthly", "annually" ] }, "tax_id": { "type": "string", "format": "uuid" }, "tax_percentage": { "type": "string", "pattern": "^(?:0*(?:[0-9]|[1-9][0-9])(?:\\\\.[0-9]{1,2})?|0*100(?:\\\\.0{1,2})?)$", "example": "16.00" }, "discount_percentage": { "type": "string", "pattern": "^(?:0*(?:[0-9]|[1-9][0-9])(?:\\\\.[0-9]{1,2})?|0*100(?:\\\\.0{1,2})?)$", "example": "0.00" }, "accounting_account_id": { "type": "string", "format": "uuid" }, "accounting_center_id": { "type": "string", "format": "uuid", "nullable": true } }, "type": "object" }, "ContractActivationItem": { "required": [ "id", "contract_item_id", "category_id", "item_id", "item_name", "quantity", "tariff_period", "agreed_rate", "subtotal", "tax_id", "tax_percentage", "discount_percentage", "accounting_account_id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "contract_item_id": { "type": "string", "format": "uuid" }, "category_id": { "type": "string", "format": "uuid" }, "item_id": { "type": "string", "format": "uuid" }, "item_name": { "type": "string", "maxLength": 255 }, "quantity": { "type": "string", "pattern": "^\\\\d+(\\\\.\\\\d{1,4})?$", "example": "1.0000" }, "tariff_period": { "type": "string", "enum": [ "semi_monthly", "monthly", "annually" ] }, "agreed_rate": { "description": "Inherited from the Contract Item; not writable on create or update", "type": "string", "pattern": "^\\\\d+(\\\\.\\\\d{1,2})?$", "readOnly": true, "example": "100.00" }, "subtotal": { "type": "string", "example": "100.00" }, "tax_id": { "type": "string", "format": "uuid" }, "tax_percentage": { "type": "string", "pattern": "^(?:0*(?:[0-9]|[1-9][0-9])(?:\\\\.[0-9]{1,2})?|0*100(?:\\\\.0{1,2})?)$", "example": "16.00" }, "discount_percentage": { "type": "string", "pattern": "^(?:0*(?:[0-9]|[1-9][0-9])(?:\\\\.[0-9]{1,2})?|0*100(?:\\\\.0{1,2})?)$", "example": "0.00" }, "accounting_account_id": { "type": "string", "format": "uuid" }, "accounting_center_id": { "type": "string", "format": "uuid", "nullable": true } }, "type": "object" }, "ContractActivationCreateRequest": { "required": [ "id", "contract_id", "client_id", "start_date", "due_date", "activation_date", "billing_start_date", "items" ], "properties": { "id": { "type": "string", "format": "uuid" }, "contract_id": { "type": "string", "format": "uuid" }, "client_id": { "type": "string", "format": "uuid" }, "start_date": { "type": "string", "format": "date" }, "due_date": { "type": "string", "format": "date" }, "activation_date": { "type": "string", "format": "date" }, "billing_start_date": { "type": "string", "format": "date" }, "observations": { "type": "string", "nullable": true }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/ContractActivationWriteItem" }, "minItems": 1 }, "preview": { "description": "Optional scale-2 preview. String amounts only. Null skips the comparison.", "properties": { "subtotal": { "type": "string", "pattern": "^\\\\d+(?:\\\\.\\\\d{1,2})?$" }, "discount": { "type": "string", "pattern": "^\\\\d+(?:\\\\.\\\\d{1,2})?$" }, "taxes": { "type": "string", "pattern": "^\\\\d+(?:\\\\.\\\\d{1,2})?$" }, "total": { "type": "string", "pattern": "^\\\\d+(?:\\\\.\\\\d{1,2})?$" }, "tax_groups": { "type": "array", "items": { "properties": { "tax_id": { "type": "string", "format": "uuid" }, "tax_percentage": { "type": "string" }, "base": { "type": "string" }, "tax": { "type": "string" } }, "type": "object" } } }, "type": "object", "nullable": true } }, "type": "object" }, "ContractActivationUpdateRequest": { "required": [ "contract_id", "client_id", "start_date", "due_date", "activation_date", "billing_start_date", "items" ], "properties": { "contract_id": { "type": "string", "format": "uuid" }, "client_id": { "type": "string", "format": "uuid" }, "start_date": { "type": "string", "format": "date" }, "due_date": { "type": "string", "format": "date" }, "activation_date": { "type": "string", "format": "date" }, "billing_start_date": { "type": "string", "format": "date" }, "observations": { "type": "string", "nullable": true }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/ContractActivationWriteItem" }, "minItems": 1 }, "preview": { "description": "Optional scale-2 preview. String amounts only. Null skips the comparison.", "properties": { "subtotal": { "type": "string", "pattern": "^\\\\d+(?:\\\\.\\\\d{1,2})?$" }, "discount": { "type": "string", "pattern": "^\\\\d+(?:\\\\.\\\\d{1,2})?$" }, "taxes": { "type": "string", "pattern": "^\\\\d+(?:\\\\.\\\\d{1,2})?$" }, "total": { "type": "string", "pattern": "^\\\\d+(?:\\\\.\\\\d{1,2})?$" }, "tax_groups": { "type": "array", "items": { "properties": { "tax_id": { "type": "string", "format": "uuid" }, "tax_percentage": { "type": "string" }, "base": { "type": "string" }, "tax": { "type": "string" } }, "type": "object" } } }, "type": "object", "nullable": true } }, "type": "object" }, "ContractActivationMutationResponse": { "required": [ "id", "code", "status" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string", "example": "ACT2600001" }, "status": { "type": "string", "enum": [ "to_approve", "active", "processed", "canceled", "ended" ] } }, "type": "object" }, "ContractActivationProblem": { "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "error_code": { "type": "string", "nullable": true }, "errors": { "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" }, "ContractActivationRecord": { "required": [ "id", "code", "contract_id", "client_id", "company_id", "start_date", "due_date", "activation_date", "billing_start_date", "status", "observations", "subtotal", "discount", "taxes", "total", "items", "client_name", "contract_code", "contract_responsible_user_id", "contract_responsible_user_name", "created_at", "updated_at", "labels" ], "properties": { "id": { "type": "string", "format": "uuid" }, "contract_id": { "type": "string", "format": "uuid" }, "client_id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "code": { "type": "string", "example": "ACT2600001" }, "start_date": { "type": "string", "format": "date" }, "due_date": { "type": "string", "format": "date" }, "activation_date": { "type": "string", "format": "date" }, "billing_start_date": { "type": "string", "format": "date" }, "status": { "type": "string", "enum": [ "to_approve", "active", "processed", "canceled", "ended" ] }, "observations": { "type": "string", "nullable": true }, "subtotal": { "type": "string", "example": "100.00" }, "discount": { "type": "string", "example": "100.00" }, "taxes": { "type": "string", "example": "100.00" }, "total": { "type": "string", "example": "100.00" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/ContractActivationItem" } }, "client_name": { "type": "string", "nullable": true }, "contract_code": { "type": "string", "nullable": true }, "contract_responsible_user_name": { "type": "string", "nullable": true }, "contract_responsible_user_id": { "description": "Inherited read-only company member identity", "type": "string", "pattern": "^[0-9]+$", "nullable": true }, "created_at": { "description": "Unavailable for SQL-null legacy timestamps", "type": "string", "format": "date-time", "nullable": true }, "updated_at": { "description": "Unavailable for SQL-null legacy timestamps", "type": "string", "format": "date-time", "nullable": true }, "labels": { "type": "array", "items": { "required": [ "id", "name", "tone", "archived" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "tone": { "type": "string" }, "archived": { "type": "boolean" } }, "type": "object" } } }, "type": "object" }, "ContractActivationListResponse": { "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ContractActivationRecord" } }, "meta": { "required": [ "total", "per_page", "current_page", "counts", "label_counts" ], "properties": { "total": { "type": "integer", "minimum": 0 }, "per_page": { "type": "integer", "maximum": 100, "minimum": 1 }, "current_page": { "type": "integer", "minimum": 1 }, "counts": { "description": "All filters except status", "required": [ "to_approve", "active", "processed", "canceled", "ended" ], "properties": { "to_approve": { "type": "integer", "minimum": 0 }, "active": { "type": "integer", "minimum": 0 }, "processed": { "type": "integer", "minimum": 0 }, "canceled": { "type": "integer", "minimum": 0 }, "ended": { "type": "integer", "minimum": 0 } }, "type": "object" }, "label_counts": { "description": "All filters except label_ids; active labels only; empty object when none", "type": "object", "additionalProperties": { "type": "integer", "minimum": 0 } } }, "type": "object" } }, "type": "object" }, "ContractActivationFinancialValidation": { "required": [ "error", "detail" ], "properties": { "error": { "type": "string", "enum": [ "contract_activation_preview_mismatch", "contract_activation_tax_selection_invalid", "contract_activation_total_exceeds_storage" ] }, "detail": { "type": "string" }, "tax_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } } }, "type": "object" }, "ContractActivationHistoricalAmounts": { "required": [ "subtotal", "discount", "taxes", "total" ], "properties": { "subtotal": { "type": "string" }, "discount": { "type": "string" }, "taxes": { "type": "string" }, "total": { "type": "string" } }, "type": "object" }, "ContractActivationHistoricalDifference": { "required": [ "error", "detail", "financial_fingerprint", "previous", "proposed" ], "properties": { "error": { "type": "string", "enum": [ "contract_activation_historical_difference_acceptance_required", "contract_activation_historical_difference_acceptance_stale" ] }, "detail": { "type": "string" }, "financial_fingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "previous": { "$ref": "#/components/schemas/ContractActivationHistoricalAmounts" }, "proposed": { "$ref": "#/components/schemas/ContractActivationHistoricalAmounts" } }, "type": "object" }, "ContractChargeDetails": { "required": [ "id", "contract_id", "activation_id", "activation_item_id", "category_id", "item_id", "tax_id", "accounting_account_id", "company_id", "quantity", "tariff_amount", "tax_percentage", "discount_percentage", "subtotal", "taxes", "discount", "total", "code", "item_name", "tariff_period", "charge_date", "status", "accounting_center_id", "invoice_id", "cancellation_reason", "cancelled_by", "cancelled_at", "contract_code", "activation_code", "client_id", "client_name", "invoice_code", "item_code", "accounting_account_name", "accounting_center_name", "category_name", "tax_name", "cancelled_by_name", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "contract_id": { "type": "string", "format": "uuid" }, "activation_id": { "type": "string", "format": "uuid" }, "activation_item_id": { "type": "string", "format": "uuid" }, "category_id": { "type": "string", "format": "uuid" }, "item_id": { "type": "string", "format": "uuid" }, "tax_id": { "type": "string", "format": "uuid" }, "accounting_account_id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "quantity": { "type": "string", "pattern": "^[0-9]+[.][0-9]{4}$" }, "tariff_amount": { "type": "string", "pattern": "^[0-9]+[.][0-9]{2}$" }, "tax_percentage": { "type": "string", "pattern": "^[0-9]+[.][0-9]{2}$" }, "discount_percentage": { "type": "string", "pattern": "^[0-9]+[.][0-9]{2}$" }, "subtotal": { "type": "string", "pattern": "^[0-9]+[.][0-9]{2}$" }, "taxes": { "type": "string", "pattern": "^[0-9]+[.][0-9]{2}$" }, "discount": { "type": "string", "pattern": "^[0-9]+[.][0-9]{2}$" }, "total": { "type": "string", "pattern": "^[0-9]+[.][0-9]{2}$" }, "code": { "type": "string" }, "item_name": { "type": "string" }, "tariff_period": { "type": "string" }, "charge_date": { "type": "string", "format": "date" }, "status": { "type": "string", "enum": [ "to_be_invoiced", "invoiced", "cancelled" ] }, "accounting_center_id": { "type": "string", "nullable": true }, "invoice_id": { "type": "string", "nullable": true }, "cancellation_reason": { "type": "string", "nullable": true }, "cancelled_by": { "type": "string", "nullable": true }, "cancelled_at": { "type": "string", "format": "date-time", "nullable": true }, "contract_code": { "type": "string", "nullable": true }, "activation_code": { "type": "string", "nullable": true }, "client_id": { "type": "string", "nullable": true }, "client_name": { "type": "string", "nullable": true }, "invoice_code": { "type": "string", "nullable": true }, "item_code": { "type": "string", "nullable": true }, "accounting_account_name": { "type": "string", "nullable": true }, "accounting_center_name": { "type": "string", "nullable": true }, "category_name": { "type": "string", "nullable": true }, "tax_name": { "type": "string", "nullable": true }, "cancelled_by_name": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "nullable": true }, "updated_at": { "type": "string", "format": "date-time", "nullable": true } }, "type": "object" }, "ContractChargeCounts": { "required": [ "to_be_invoiced", "invoiced", "cancelled" ], "properties": { "to_be_invoiced": { "type": "integer", "minimum": 0 }, "invoiced": { "type": "integer", "minimum": 0 }, "cancelled": { "type": "integer", "minimum": 0 } }, "type": "object" }, "ContractChargeMeta": { "required": [ "total", "per_page", "current_page", "counts" ], "properties": { "total": { "type": "integer" }, "per_page": { "type": "integer" }, "current_page": { "type": "integer" }, "counts": { "$ref": "#/components/schemas/ContractChargeCounts" } }, "type": "object" }, "ContractChargeList": { "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ContractChargeDetails" } }, "meta": { "$ref": "#/components/schemas/ContractChargeMeta" } }, "type": "object" }, "ContractChargeCreate": { "required": [ "id", "contract_id", "activation_id", "activation_item_id", "category_id", "item_id", "item_name", "quantity", "tariff_period", "tariff_amount", "tax_id", "tax_percentage", "discount_percentage", "charge_date", "accounting_account_id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "contract_id": { "type": "string", "format": "uuid" }, "activation_id": { "type": "string", "format": "uuid" }, "activation_item_id": { "type": "string", "format": "uuid" }, "category_id": { "type": "string", "format": "uuid" }, "item_id": { "type": "string", "format": "uuid" }, "item_name": { "type": "string" }, "quantity": { "type": "string", "pattern": "^[0-9]+(?:[.][0-9]{1,4})?$" }, "tariff_period": { "type": "string", "enum": [ "semi_monthly", "monthly", "annually" ] }, "tariff_amount": { "type": "string", "pattern": "^[0-9]+(?:[.][0-9]{1,2})?$" }, "tax_id": { "type": "string", "format": "uuid" }, "tax_percentage": { "type": "string", "pattern": "^(?:0*(?:[0-9]|[1-9][0-9])(?:[.][0-9]{1,2})?|0*100(?:[.]0{1,2})?)$" }, "discount_percentage": { "type": "string", "pattern": "^(?:0*(?:[0-9]|[1-9][0-9])(?:[.][0-9]{1,2})?|0*100(?:[.]0{1,2})?)$" }, "charge_date": { "type": "string", "format": "date" }, "accounting_account_id": { "type": "string", "format": "uuid" }, "accounting_center_id": { "type": "string", "format": "uuid", "nullable": true }, "preview": { "required": [ "subtotal", "discount", "taxes", "total", "tax_groups" ], "properties": { "subtotal": { "type": "string", "pattern": "^[0-9]+[.][0-9]{2}$" }, "discount": { "type": "string", "pattern": "^[0-9]+[.][0-9]{2}$" }, "taxes": { "type": "string", "pattern": "^[0-9]+[.][0-9]{2}$" }, "total": { "type": "string", "pattern": "^[0-9]+[.][0-9]{2}$" }, "tax_groups": { "type": "array", "items": { "required": [ "tax_id", "tax_percentage", "base", "tax" ], "properties": { "tax_id": { "type": "string", "format": "uuid" }, "tax_percentage": { "type": "string" }, "base": { "type": "string" }, "tax": { "type": "string" } }, "type": "object" } } }, "type": "object", "nullable": true } }, "type": "object" }, "ContractChargeCreated": { "required": [ "id", "code", "status" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "status": { "type": "string", "enum": [ "to_be_invoiced" ] } }, "type": "object" }, "ContractChargeCancel": { "required": [ "reason" ], "properties": { "reason": { "type": "string", "maxLength": 500, "minLength": 1 } }, "type": "object" }, "ContractChargeProblem": { "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "error_code": { "type": "string", "nullable": true }, "errors": { "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" }, "ChargeContractSource": { "required": [ "id", "code", "company_id", "status", "client_name", "accounting_center_id", "accounting_center_name" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "company_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "client_name": { "type": "string", "nullable": true }, "accounting_center_id": { "type": "string", "format": "uuid" }, "accounting_center_name": { "type": "string", "nullable": true } }, "type": "object" }, "ChargeActivationSource": { "required": [ "id", "code", "company_id", "contract_id", "status", "items" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "company_id": { "type": "string", "format": "uuid" }, "contract_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/ActivationSourceLine" } } }, "type": "object" }, "ContractDeactivationItem": { "required": [ "id", "contract_item_id", "category_id", "item_id", "item_name", "quantity", "tariff_period", "agreed_rate", "tax_id", "tax_percentage", "discount_percentage", "accounting_account_id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "contract_item_id": { "type": "string", "format": "uuid" }, "category_id": { "type": "string", "format": "uuid" }, "item_id": { "type": "string", "format": "uuid" }, "item_name": { "type": "string", "maxLength": 255 }, "quantity": { "type": "string", "pattern": "^\\\\d+(\\\\.\\\\d{1,4})?$", "example": "1.0000" }, "tariff_period": { "type": "string", "enum": [ "semi_monthly", "monthly", "annually" ] }, "agreed_rate": { "description": "Copied from the Activation; not writable on create or update", "type": "string", "pattern": "^\\\\d+(\\\\.\\\\d{1,2})?$", "readOnly": true, "example": "100.00" }, "subtotal": { "type": "string", "example": "100.00" }, "tax_id": { "type": "string", "format": "uuid" }, "tax_percentage": { "type": "string", "pattern": "^(?:0*(?:[0-9]|[1-9][0-9])(?:\\\\.[0-9]{1,2})?|0*100(?:\\\\.0{1,2})?)$", "example": "16.00" }, "discount_percentage": { "type": "string", "pattern": "^(?:0*(?:[0-9]|[1-9][0-9])(?:\\\\.[0-9]{1,2})?|0*100(?:\\\\.0{1,2})?)$", "example": "0.00" }, "accounting_account_id": { "type": "string", "format": "uuid" } }, "type": "object" }, "ContractDeactivationProblem": { "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "error_code": { "type": "string", "nullable": true }, "errors": { "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" }, "ContractDeactivationRecord": { "required": [ "id", "code", "contract_id", "client_id", "company_id", "start_date", "due_date", "activation_date", "billing_start_date", "deactivation_date", "activation_id", "status", "observations", "subtotal", "discount", "taxes", "total", "items", "client_name", "contract_code", "contract_status", "activation_code", "approval_activity", "contract_responsible_user_id", "contract_responsible_user_name", "created_at", "updated_at", "labels" ], "properties": { "id": { "type": "string", "format": "uuid" }, "activation_id": { "type": "string", "format": "uuid" }, "deactivation_date": { "type": "string", "format": "date" }, "contract_id": { "type": "string", "format": "uuid" }, "client_id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "code": { "type": "string", "example": "DES2600001" }, "start_date": { "type": "string", "format": "date" }, "due_date": { "type": "string", "format": "date" }, "activation_date": { "type": "string", "format": "date" }, "billing_start_date": { "type": "string", "format": "date" }, "status": { "type": "string", "enum": [ "to_approve", "approved", "canceled" ] }, "observations": { "type": "string", "nullable": true }, "subtotal": { "type": "string", "example": "100.00" }, "discount": { "type": "string", "example": "100.00" }, "taxes": { "type": "string", "example": "100.00" }, "total": { "type": "string", "example": "100.00" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/ContractDeactivationItem" } }, "contract_status": { "type": "string", "nullable": true }, "activation_code": { "type": "string", "nullable": true }, "approval_activity": { "required": [ "history_id", "event_kind", "code", "contract_id", "contract_code", "activation_id", "activation_code", "deactivation_date", "is_last_active_activation", "actor_name", "occurred_on" ], "properties": { "history_id": { "type": "string", "format": "uuid" }, "event_kind": { "type": "string", "enum": [ "approved" ] }, "code": { "type": "string" }, "contract_id": { "type": "string", "format": "uuid" }, "contract_code": { "type": "string", "nullable": true }, "activation_id": { "type": "string", "format": "uuid" }, "activation_code": { "type": "string", "nullable": true }, "deactivation_date": { "type": "string", "format": "date" }, "is_last_active_activation": { "description": "Captured locked approval fact, never inferred from current active count", "type": "boolean" }, "actor_name": { "type": "string" }, "occurred_on": { "type": "string", "format": "date-time" } }, "type": "object", "nullable": true }, "client_name": { "type": "string", "nullable": true }, "contract_code": { "type": "string", "nullable": true }, "contract_responsible_user_name": { "type": "string", "nullable": true }, "contract_responsible_user_id": { "description": "Inherited read-only company member identity", "type": "string", "pattern": "^[0-9]+$", "nullable": true }, "created_at": { "description": "Unavailable for SQL-null legacy timestamps", "type": "string", "format": "date-time", "nullable": true }, "updated_at": { "description": "Unavailable for SQL-null legacy timestamps", "type": "string", "format": "date-time", "nullable": true }, "labels": { "type": "array", "items": { "required": [ "id", "name", "tone", "archived" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "tone": { "type": "string" }, "archived": { "type": "boolean" } }, "type": "object" } } }, "type": "object" }, "ContractDeactivationListResponse": { "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ContractDeactivationRecord" } }, "meta": { "required": [ "total", "per_page", "current_page", "counts", "label_counts" ], "properties": { "total": { "type": "integer", "minimum": 0 }, "per_page": { "type": "integer", "maximum": 100, "minimum": 1 }, "current_page": { "type": "integer", "minimum": 1 }, "counts": { "description": "All filters except status", "required": [ "to_approve", "approved", "canceled" ], "properties": { "to_approve": { "type": "integer", "minimum": 0 }, "approved": { "type": "integer", "minimum": 0 }, "canceled": { "type": "integer", "minimum": 0 } }, "type": "object" }, "label_counts": { "description": "All filters except label_ids; active labels only; empty object when none", "type": "object", "additionalProperties": { "type": "integer", "minimum": 0 } } }, "type": "object" } }, "type": "object" }, "ContractDeactivationHistoricalAmounts": { "required": [ "subtotal", "discount", "taxes", "total" ], "properties": { "subtotal": { "type": "string" }, "discount": { "type": "string" }, "taxes": { "type": "string" }, "total": { "type": "string" } }, "type": "object" }, "ContractDeactivationHistoricalDifference": { "required": [ "error", "detail", "financial_fingerprint", "previous", "proposed" ], "properties": { "error": { "type": "string", "enum": [ "contract_deactivation_historical_difference_acceptance_required", "contract_deactivation_historical_difference_acceptance_stale" ] }, "detail": { "type": "string" }, "financial_fingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "previous": { "$ref": "#/components/schemas/ContractDeactivationHistoricalAmounts" }, "proposed": { "$ref": "#/components/schemas/ContractDeactivationHistoricalAmounts" } }, "type": "object" }, "DeactivationActivationSource": { "required": [ "id", "code", "company_id", "contract_id", "client_id", "status", "start_date", "due_date", "activation_date", "billing_start_date", "observations", "subtotal", "discount", "taxes", "total", "items", "client_name", "contract_code" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "company_id": { "type": "string", "format": "uuid" }, "contract_id": { "type": "string", "format": "uuid" }, "client_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "start_date": { "type": "string", "format": "date" }, "due_date": { "type": "string", "format": "date" }, "activation_date": { "type": "string", "format": "date" }, "billing_start_date": { "type": "string", "format": "date" }, "observations": { "type": "string", "nullable": true }, "subtotal": { "type": "string" }, "discount": { "type": "string" }, "taxes": { "type": "string" }, "total": { "type": "string" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/ActivationSourceLine" } }, "client_name": { "type": "string", "nullable": true }, "contract_code": { "type": "string", "nullable": true } }, "type": "object" }, "ContractProblemResponse": { "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "error_code": { "type": "string", "nullable": true }, "errors": { "type": "object", "nullable": true } }, "type": "object" }, "ContractMiddlewareForbiddenResponse": { "required": [ "title", "status", "detail" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer", "example": 403 }, "detail": { "type": "string" } }, "type": "object", "additionalProperties": false }, "ContractMiddlewareMessageResponse": { "required": [ "message" ], "properties": { "message": { "type": "string" } }, "type": "object" }, "ContractRequestValidationResponse": { "required": [ "message", "errors" ], "properties": { "message": { "type": "string" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" }, "ContractFinancialValidationResponse": { "required": [ "error", "detail" ], "properties": { "error": { "type": "string" }, "detail": { "type": "string" }, "tax_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } } }, "type": "object", "additionalProperties": false }, "ContractHistoricalAmounts": { "required": [ "subtotal", "discount", "taxes", "total" ], "properties": { "subtotal": { "type": "string", "example": "100.00" }, "discount": { "type": "string", "example": "0.00" }, "taxes": { "type": "string", "example": "16.00" }, "total": { "type": "string", "example": "116.00" } }, "type": "object" }, "ContractHistoricalDifferenceResponse": { "required": [ "error", "detail", "financial_fingerprint", "previous", "proposed" ], "properties": { "error": { "type": "string", "enum": [ "contract_historical_difference_acceptance_required", "contract_historical_difference_acceptance_stale" ] }, "detail": { "type": "string" }, "financial_fingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "previous": { "$ref": "#/components/schemas/ContractHistoricalAmounts" }, "proposed": { "$ref": "#/components/schemas/ContractHistoricalAmounts" } }, "type": "object" }, "PosReceipt": { "description": "Ticket no fiscal (ADR 0219). It never carries «Factura», the invoice or control number, the fiscal-machine serial, «SENIAT», or VAT totals or breakdown. Line amounts include VAT. A line's unit_price is the item's own price, less its discount, plus its tax, rounded once, so unit_price × quantity can differ from the line total by rounding; and the lines can differ from `total` by per-tax-group rounding. `total` is the charged total. A voided sale's ticket keeps all of it, «DOCUMENTO NO FISCAL» included, and adds «ANULADA», when, why, and who voided and authorized it (MER-4979).", "required": [ "id", "code", "title", "footer", "status", "company", "sold_at", "counter_salesperson", "cash_register", "lines", "total", "counterpart", "payments", "buyer", "voided" ], "properties": { "id": { "description": "The counter sale read components (MER-4975): the Ticket no fiscal, the\nrows of a Turno's sales and a Caja's pending refunds (MER-4979). They\npublish exactly what the read models emit; money reuses PosQuoteMoney.", "type": "string", "format": "uuid" }, "code": { "description": "The sale code: the last six characters of the id, uppercased. Not fiscal, not unique.", "type": "string", "example": "A3F09C" }, "title": { "type": "string", "enum": [ "DOCUMENTO NO FISCAL" ] }, "footer": { "type": "string", "enum": [ "Sin valor fiscal" ] }, "status": { "description": "Where the sale stands: completed once charged, voided once its Anulación recorded it (MER-4978).", "type": "string", "enum": [ "completed", "voided" ] }, "company": { "required": [ "name" ], "properties": { "name": { "description": "The fiscal profile's legal name when one is configured, else the company's name.", "type": "string", "example": "QA Fiscal Company, C.A." } }, "type": "object" }, "sold_at": { "description": "ISO 8601 in the company's offset.", "type": "string", "format": "date-time", "example": "2026-10-29T12:00:00-04:00" }, "counter_salesperson": { "description": "The Vendedora who charged the sale; her name is null once she is no longer a member of the company.", "required": [ "id", "name" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string", "nullable": true } }, "type": "object" }, "cash_register": { "required": [ "id", "name" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "example": "Caja CAJA-1", "nullable": true } }, "type": "object" }, "lines": { "type": "array", "items": { "required": [ "index", "description", "quantity", "unit", "unit_price", "total" ], "properties": { "index": { "type": "integer" }, "description": { "type": "string", "example": "Harina PAN 1 kg" }, "quantity": { "type": "string", "example": "2.0000" }, "unit": { "required": [ "id", "name" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "example": "Unidad", "nullable": true } }, "type": "object" }, "unit_price": { "description": "The item's own price, less its discount, plus its tax, rounded half-up once: the shelf price whatever the quantity. Times the quantity it can differ from the line total by rounding.", "allOf": [ { "$ref": "#/components/schemas/PosQuoteMoney" } ] }, "total": { "description": "What the buyer pays for the line, VAT included.", "allOf": [ { "$ref": "#/components/schemas/PosQuoteMoney" } ] } }, "type": "object" } }, "total": { "description": "The charged total in the document currency.", "allOf": [ { "$ref": "#/components/schemas/PosQuoteMoney" } ] }, "counterpart": { "description": "The charged total at the official document rate, or null without one.", "required": [ "amount", "currency" ], "properties": { "amount": { "type": "string", "example": "846.80" }, "currency": { "type": "string", "enum": [ "USD", "VES" ] } }, "type": "object", "nullable": true }, "payments": { "description": "Each payment as the sale charged it, in request order.", "type": "array", "items": { "required": [ "index", "instrument", "amount", "rate", "igtf", "reference" ], "properties": { "index": { "type": "integer" }, "instrument": { "required": [ "id", "name" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "example": "Efectivo USD", "nullable": true } }, "type": "object" }, "amount": { "description": "The money received, in the instrument's currency, IGTF included.", "allOf": [ { "$ref": "#/components/schemas/PosQuoteMoney" } ] }, "rate": { "required": [ "value_date", "rate" ], "properties": { "value_date": { "type": "string", "format": "date" }, "rate": { "type": "string", "example": "36.50000000" } }, "type": "object" }, "igtf": { "description": "Its IGTF (ADR 0193).", "required": [ "outcome", "percentage", "amount" ], "properties": { "outcome": { "type": "string", "enum": [ "not_evaluated", "not_perceived", "perceived", "unclassified" ] }, "percentage": { "type": "string", "example": "3.00", "nullable": true }, "amount": { "description": "The IGTF Perceived, in the instrument's currency.", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/PosQuoteMoney" } ] } }, "type": "object" }, "reference": { "description": "The operation's reference as the collection keeps it; null for cash.", "type": "string", "example": "0102-123456", "nullable": true } }, "type": "object" } }, "buyer": { "description": "Only when one was given (ADR 0220): the buyer the counter captured, or the Client chosen at the till with its frozen document and legal name. Null for an anonymous Consumidor final.", "required": [ "document", "name" ], "properties": { "document": { "required": [ "type", "number" ], "properties": { "type": { "type": "string", "enum": [ "rif", "cedula", "passport" ] }, "number": { "type": "string", "example": "V-12345678" } }, "type": "object", "nullable": true }, "name": { "type": "string", "example": "Ana Pérez", "nullable": true } }, "type": "object", "nullable": true }, "voided": { "description": "The Anulación of a voided sale (MER-4979); null for a completed sale. It adds nothing fiscal: the reason is the cashier's own words, printed as written.", "required": [ "mark", "at", "reason", "voided_by", "authorized_by" ], "properties": { "mark": { "description": "The word the till prints on the ticket.", "type": "string", "enum": [ "ANULADA" ] }, "at": { "description": "When the sale was voided, ISO 8601 in the company's offset.", "type": "string", "format": "date-time", "example": "2026-10-29T12:00:00-04:00" }, "reason": { "description": "Why it was voided, trimmed.", "type": "string", "example": "La clienta se arrepintió" }, "voided_by": { "description": "The user who voided it; the name is null once they are no longer a member of the company.", "required": [ "id", "name" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string", "example": "Ana Pérez", "nullable": true } }, "type": "object" }, "authorized_by": { "description": "The owner who granted the Autorización de la dueña, or the user who voided it on their own authority as a holder of backoffice.sales.counter-sales.void; the name is null once they are no longer a member of the company.", "required": [ "id", "name" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string", "example": "María Gómez", "nullable": true } }, "type": "object" } }, "type": "object", "nullable": true } }, "type": "object" }, "CounterSaleView": { "required": [ "id", "code", "sold_at", "status", "counter_salesperson", "currency", "total", "payments" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "description": "The sale code; not fiscal, not unique.", "type": "string", "example": "A3F09C" }, "sold_at": { "description": "ISO 8601 in the company's offset.", "type": "string", "format": "date-time", "example": "2026-10-29T12:05:00-04:00" }, "status": { "description": "completed once charged, voided once its Anulación recorded it (MER-4978).", "type": "string", "enum": [ "completed", "voided" ] }, "counter_salesperson": { "required": [ "id", "name" ], "properties": { "id": { "type": "integer" }, "name": { "description": "Null once she is no longer a member of the company.", "type": "string", "nullable": true } }, "type": "object" }, "currency": { "type": "string", "enum": [ "USD", "VES" ] }, "total": { "description": "The charged total.", "allOf": [ { "$ref": "#/components/schemas/PosQuoteMoney" } ] }, "payments": { "type": "array", "items": { "required": [ "index", "instrument", "amount" ], "properties": { "index": { "type": "integer" }, "instrument": { "required": [ "id", "name" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "example": "Efectivo USD", "nullable": true } }, "type": "object" }, "amount": { "description": "The money received, in the instrument's currency, IGTF included.", "allOf": [ { "$ref": "#/components/schemas/PosQuoteMoney" } ] } }, "type": "object" } } }, "type": "object" }, "CounterSaleViewPage": { "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CounterSaleView" } }, "meta": { "required": [ "total", "per_page", "current_page", "counts" ], "properties": { "total": { "description": "How many sales the Turno holds: completed plus voided.", "type": "integer" }, "per_page": { "type": "integer" }, "current_page": { "type": "integer" }, "counts": { "description": "How many sales the whole Turno holds in each status, the same on every page (MER-5151).", "required": [ "completed", "voided" ], "properties": { "completed": { "description": "Every completed sale of the Turno, on every page.", "type": "integer", "minimum": 0 }, "voided": { "description": "Every voided sale of the Turno, on every page.", "type": "integer", "minimum": 0 } }, "type": "object" } }, "type": "object" } }, "type": "object" }, "PendingCounterSaleRefund": { "description": "An electronic Reembolso de anulación still waiting for its external reference (MER-4979).", "required": [ "id", "sale", "instrument", "amount", "voided_at", "age_seconds" ], "properties": { "id": { "description": "The refund's id, which POST pos/sales/{id}/refunds/{refundId}/confirm takes.", "type": "string", "format": "uuid" }, "sale": { "description": "The voided sale.", "required": [ "id", "code" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "description": "The sale code; not fiscal, not unique.", "type": "string", "example": "A3F09C" } }, "type": "object" }, "instrument": { "required": [ "id", "name" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "example": "Pago móvil", "nullable": true } }, "type": "object" }, "amount": { "description": "What goes back, in the instrument's currency, IGTF included.", "allOf": [ { "$ref": "#/components/schemas/PosQuoteMoney" } ] }, "voided_at": { "description": "When the sale was voided, ISO 8601 in the company's offset.", "type": "string", "format": "date-time", "example": "2026-10-29T12:00:00-04:00" }, "age_seconds": { "description": "Seconds since voided_at by the server's clock, never less than 0.", "type": "integer", "example": 5400, "minimum": 0 } }, "type": "object" }, "PendingCounterSaleRefundPage": { "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PendingCounterSaleRefund" } }, "meta": { "required": [ "total", "per_page", "current_page" ], "properties": { "total": { "description": "How many refunds of the Caja are pending.", "type": "integer" }, "per_page": { "type": "integer" }, "current_page": { "type": "integer" } }, "type": "object" } }, "type": "object" }, "PosRouteNotFound": { "description": "The router's answer for a path id that is not a UUID, before the controller.", "required": [ "message" ], "properties": { "message": { "type": "string" } }, "type": "object" }, "CounterSaleChargeRequest": { "required": [ "cash_register_id", "lines", "payments", "idempotency_key", "quote_fingerprint" ], "properties": { "cash_register_id": { "description": "The Caja that sells: it must be active, name an active pos Canal and have an open Turno.", "type": "string", "format": "uuid" }, "currency": { "description": "The document currency. Omitted or null takes the currency of the Canal's default list, else USD.", "type": "string", "nullable": true, "enum": [ "USD", "VES" ] }, "buyer": { "description": "Who buys. Omitted or null is the Consumidor final without a document.", "required": [ "kind" ], "properties": { "kind": { "type": "string", "enum": [ "final_consumer", "client" ] }, "client_id": { "description": "Required with kind client, prohibited otherwise.", "type": "string", "format": "uuid", "nullable": true }, "document_type": { "description": "final_consumer only: V or E (cédula of 5 to 8 digits), J or G (RIF of 9 digits) or P (passport). Prohibited with kind client.", "type": "string", "nullable": true, "maxLength": 1 }, "document_number": { "description": "final_consumer only: the document's digits. Prohibited with kind client.", "type": "string", "nullable": true, "maxLength": 10 }, "name": { "description": "final_consumer only: up to 120 characters once spaces collapse. Prohibited with kind client.", "type": "string", "nullable": true, "maxLength": 255 } }, "type": "object", "nullable": true, "additionalProperties": false }, "lines": { "type": "array", "items": { "required": [ "item_id", "quantity" ], "properties": { "item_id": { "type": "string", "format": "uuid" }, "unit_id": { "description": "Omitted or null sells the Item's base unit.", "type": "string", "format": "uuid", "nullable": true }, "quantity": { "description": "Positive, up to 11 integer digits and 4 decimals.", "type": "string", "pattern": "^(?:[1-9]\\d{0,10}(?:\\.\\d{1,4})?|0\\.(?=\\d*[1-9])\\d{1,4})$", "example": "2" } }, "type": "object", "additionalProperties": false }, "maxItems": 200, "minItems": 1 }, "payments": { "description": "How the sale is paid: they must settle the total within the collection's tolerance, with no change.", "type": "array", "items": { "required": [ "payment_instrument_id", "amount" ], "properties": { "payment_instrument_id": { "description": "One of the Caja's rails.", "type": "string", "format": "uuid" }, "amount": { "description": "Positive, in the instrument's currency, IGTF included, up to 13 integer digits and 2 decimals.", "type": "string", "pattern": "^(?:[1-9]\\d{0,12}(?:\\.\\d{1,2})?|0\\.(?=\\d*[1-9])\\d{1,2})$", "example": "13.20" }, "reference": { "description": "Required on a rail that requires_reference (every class but cash): else 422 counter_sale_payment_reference_required. Kept on the collection only.", "type": "string", "nullable": true, "maxLength": 100 } }, "type": "object", "additionalProperties": false }, "maxItems": 10, "minItems": 1 }, "idempotency_key": { "description": "Unique per company and bound to the Vendedora: a retry resends the same body under it. 1 to 100 of A-Z, a-z, 0-9, \".\", \"_\", \":\" or \"-\", compared exactly.", "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,100}$", "example": "caja-1:0199e974-0000-4000-8000-000000000001", "maxLength": 100 }, "quote_fingerprint": { "description": "The quote_fingerprint of the Cotización POS the till showed; the charge quotes again and answers 409 quote_changed when it differs.", "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "type": "object" }, "WebOrderCounterSaleChargeRequest": { "description": "A till charging a Pedido web it holds (MER-5432, ADR 0361-a-pos-charge, ADR 0362): the same body as its quote, with the key and the Huella it accepted. Merchandise, buyer and currency come from the order, so lines, buyer and currency are refused (422) rather than compared. Sending a non-null web_order_id is what selects this body.", "required": [ "cash_register_id", "web_order_id", "expected_version", "claim_cycle_id", "payments", "idempotency_key", "quote_fingerprint" ], "properties": { "cash_register_id": { "description": "The Caja whose open Turno claimed the order.", "type": "string", "format": "uuid" }, "web_order_id": { "type": "string", "format": "uuid" }, "expected_version": { "description": "The version the till read; a buyer's rail change moves it.", "type": "integer", "minimum": 1 }, "claim_cycle_id": { "description": "The cycle of the claim this seller holds.", "type": "string", "format": "uuid" }, "payments": { "description": "One to ten; they must settle the total at today's rate, within the collection's tolerance. Every rail but cash requires its reference.", "type": "array", "items": { "required": [ "payment_instrument_id", "amount" ], "properties": { "payment_instrument_id": { "description": "One of the Caja's rails.", "type": "string", "format": "uuid" }, "amount": { "description": "Positive, in the instrument's currency, up to 13 integer digits and 2 decimals.", "type": "string", "pattern": "^(?:[1-9]\\d{0,12}(?:\\.\\d{1,2})?|0\\.(?=\\d*[1-9])\\d{1,2})$", "example": "1200.00" }, "reference": { "type": "string", "nullable": true, "maxLength": 100 } }, "type": "object", "additionalProperties": false }, "maxItems": 10, "minItems": 1 }, "idempotency_key": { "description": "Unique per company and bound to the Vendedora: a retry resends the same body under it. 1 to 100 of A-Z, a-z, 0-9, \".\", \"_\", \":\" or \"-\", compared exactly.", "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,100}$", "maxLength": 100 }, "quote_fingerprint": { "description": "The Huella the till accepted.", "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "type": "object", "additionalProperties": false }, "CounterSale": { "required": [ "id", "code", "sales_invoice_id", "collection_id", "cash_shift_id", "currency", "totals", "payments", "counter_salesperson" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "description": "The sale code the ticket shows: the last six characters of the id, uppercased. Not fiscal.", "type": "string", "example": "A3F09C" }, "sales_invoice_id": { "description": "The approved cash Sales Invoice of the Caja's Canal.", "type": "string", "format": "uuid" }, "collection_id": { "description": "The applied Collection, one method line per payment, attributed to the Turno.", "type": "string", "format": "uuid" }, "cash_shift_id": { "description": "The Turno the sale was charged on.", "type": "string", "format": "uuid" }, "currency": { "type": "string", "enum": [ "USD", "VES" ] }, "totals": { "description": "As the charged quote totalled them, with their counterpart at the official document rate (null without one).", "required": [ "subtotal", "taxes", "total", "counterpart" ], "properties": { "subtotal": { "allOf": [ { "$ref": "#/components/schemas/PosQuoteMoney" } ] }, "taxes": { "allOf": [ { "$ref": "#/components/schemas/PosQuoteMoney" } ] }, "total": { "allOf": [ { "$ref": "#/components/schemas/PosQuoteMoney" } ] }, "counterpart": { "required": [ "currency", "subtotal", "taxes", "total" ], "properties": { "currency": { "type": "string", "enum": [ "USD", "VES" ] }, "subtotal": { "type": "string", "example": "730.00" }, "taxes": { "type": "string", "example": "116.80" }, "total": { "type": "string", "example": "846.80" } }, "type": "object", "nullable": true } }, "type": "object" }, "payments": { "description": "Each payment as the collection settled it, in request order; its reference stays on the collection.", "type": "array", "items": { "required": [ "index", "payment_instrument_id", "class", "amount", "applied", "rate", "igtf" ], "properties": { "index": { "type": "integer" }, "payment_instrument_id": { "type": "string", "format": "uuid" }, "class": { "type": "string", "example": "cash" }, "amount": { "description": "The money received, in the instrument's currency, IGTF included.", "allOf": [ { "$ref": "#/components/schemas/PosQuoteMoney" } ] }, "applied": { "description": "The debt it settled in the document currency.", "allOf": [ { "$ref": "#/components/schemas/PosQuoteMoney" } ] }, "rate": { "description": "The official rate of its cash event.", "required": [ "value_date", "rate" ], "properties": { "value_date": { "type": "string", "format": "date" }, "rate": { "type": "string", "example": "36.50000000" } }, "type": "object" }, "igtf": { "description": "Its IGTF (ADR 0193).", "required": [ "outcome", "percentage", "amount", "cause" ], "properties": { "outcome": { "type": "string", "enum": [ "not_evaluated", "not_perceived", "perceived", "unclassified" ] }, "percentage": { "type": "string", "example": "3.00", "nullable": true }, "amount": { "description": "The IGTF Perceived, in the instrument's currency.", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/PosQuoteMoney" } ] }, "cause": { "type": "string", "nullable": true } }, "type": "object" } }, "type": "object" } }, "counter_salesperson": { "description": "The Vendedora who charged the sale: the authenticated user.", "required": [ "id", "name" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "type": "object" } }, "type": "object" }, "CounterSaleProblem": { "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "error_code": { "type": "string", "nullable": true }, "errors": { "description": "Request validation messages by field, or counter_sale_payment_reference_required by payments.N.reference.", "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "cash_register_id": { "description": "With cash_shift_not_open.", "type": "string", "format": "uuid" }, "reason": { "description": "With counter_sale_cash_register_not_selling.", "type": "string", "enum": [ "cash_register_inactive", "no_sales_channel", "sales_channel_not_found", "sales_channel_inactive", "sales_channel_not_pos" ] }, "lines": { "description": "With counter_sale_item_not_found ([index, item_id]), counter_sale_line_unpriced ([index, item_id, status]) or counter_sale_line_not_chargeable ([index, item_id, blocked_by]).", "type": "array", "items": { "required": [ "index", "item_id" ], "properties": { "index": { "type": "integer" }, "item_id": { "type": "string" }, "status": { "type": "string", "enum": [ "unpriced", "rate_unavailable", "rounds_to_zero" ] }, "blocked_by": { "type": "array", "items": { "type": "string", "enum": [ "item_inactive", "sales_tax_missing", "revenue_account_missing", "accounting_center_missing" ] } } }, "type": "object" } }, "payments": { "description": "With counter_sale_payment_instrument_not_a_rail: each payment off the Caja's rails.", "type": "array", "items": { "required": [ "index", "payment_instrument_id" ], "properties": { "index": { "type": "integer" }, "payment_instrument_id": { "type": "string" } }, "type": "object" } }, "remaining": { "description": "With counter_sale_payments_do_not_settle: what is still to pay, negative when the payments derive more.", "allOf": [ { "$ref": "#/components/schemas/PosQuoteMoney" } ] }, "settlement": { "description": "With counter_sale_payments_do_not_settle: the settlement as the Cotización POS shows it.", "required": [ "total", "applied", "remaining", "rounding", "settles" ], "properties": { "total": { "allOf": [ { "$ref": "#/components/schemas/PosQuoteMoney" } ] }, "applied": { "allOf": [ { "$ref": "#/components/schemas/PosQuoteMoney" } ] }, "remaining": { "allOf": [ { "$ref": "#/components/schemas/PosQuoteMoney" } ] }, "rounding": { "allOf": [ { "$ref": "#/components/schemas/PosQuoteMoney" } ] }, "settles": { "type": "boolean" } }, "type": "object", "nullable": true }, "insufficient_stock_items": { "description": "With insufficient_stock: each line the Disponible no longer covers.", "type": "array", "items": { "required": [ "item_id", "location_id", "requested_quantity", "sellable_quantity", "base_unit_name" ], "properties": { "item_id": { "type": "string", "format": "uuid" }, "location_id": { "type": "string", "format": "uuid" }, "requested_quantity": { "type": "string" }, "sellable_quantity": { "type": "string" }, "base_unit_name": { "type": "string", "nullable": true } }, "type": "object" } }, "client_id": { "description": "With counter_sale_client_not_found.", "type": "string" }, "missing": { "description": "With client_fiscal_identity_incomplete: what the Pedido web's Client lacks, and never who it is.", "type": "array", "items": { "type": "string" } }, "business_day": { "description": "With counter_sale_void_outside_store_day: the sale's Día de tienda.", "type": "string", "format": "date" }, "fiscal_period": { "description": "With document_in_frozen_fiscal_period: the period whose current Declared Set holds the invoice.", "allOf": [ { "$ref": "#/components/schemas/FrozenFiscalPeriod" } ] }, "field_errors": { "description": "With sale_price_line_unit_not_of_item: messages by lines.N.unit_id.", "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" }, "CounterSaleQuoteChangedProblem": { "required": [ "title", "status", "detail", "error_code", "errors", "quote" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "error_code": { "type": "string", "enum": [ "quote_changed" ] }, "errors": { "type": "object", "nullable": true }, "quote": { "description": "The fresh Cotización POS: the till shows it, and charges again with its quote_fingerprint.", "allOf": [ { "$ref": "#/components/schemas/PosQuote" } ] } }, "type": "object" }, "CounterSaleVoidRequest": { "required": [ "reason" ], "properties": { "reason": { "description": "Why the sale is voided: 1 to 500 characters, not blank, stored trimmed on the void only, never in its event or a log.", "type": "string", "pattern": "\\S", "example": "La clienta se arrepintió", "maxLength": 500, "minLength": 1 }, "authorization_token": { "description": "The Autorización de la dueña token POST pos/exception-approvals granted for this sale and this requester, consumed by the void. Omit it or send null when the caller holds backoffice.sales.counter-sales.void, who voids on their own authority: a token they send is ignored and not consumed.", "type": "string", "nullable": true, "maxLength": 200 } }, "type": "object" }, "CounterSaleVoid": { "required": [ "void_id", "counter_sale_id", "voided_at", "business_day", "voided_by_user_id", "authorized_by_user_id", "owner_step_up_authorization_id", "reason", "refund_cash_shift_id", "refunds" ], "properties": { "void_id": { "type": "string", "format": "uuid" }, "counter_sale_id": { "type": "string", "format": "uuid" }, "voided_at": { "type": "string", "format": "date-time", "example": "2026-10-29T20:05:00+00:00" }, "business_day": { "description": "The sale's Día de tienda, the company's today.", "type": "string", "format": "date", "example": "2026-10-29" }, "voided_by_user_id": { "description": "The authenticated user who voided the sale.", "type": "integer" }, "authorized_by_user_id": { "description": "The caller themselves as a holder of void, or the owner who granted the consumed authorization.", "type": "integer" }, "owner_step_up_authorization_id": { "description": "The consumed Autorización de la dueña; null when the caller authorized the void themselves.", "type": "string", "format": "uuid", "nullable": true }, "reason": { "description": "The reason, trimmed.", "type": "string" }, "refund_cash_shift_id": { "description": "The open Turno of the sale's Caja whose drawer paid the cash back; null when no payment was in cash.", "type": "string", "format": "uuid", "nullable": true }, "refunds": { "description": "One per payment the sale froze, in payment order.", "type": "array", "items": { "$ref": "#/components/schemas/CounterSaleRefund" } } }, "type": "object" }, "CounterSaleRefund": { "description": "A «Reembolso de anulación»: the return of one payment of a voided sale. The void answers it refunded or pending_confirmation; its confirmation (POST pos/sales/{id}/refunds/{refundId}/confirm) answers it confirmed.", "required": [ "id", "payment_index", "payment_instrument_id", "amount", "status", "external_reference", "confirmed_at", "confirmed_by_user_id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "payment_index": { "description": "The index of the payment it returns: one instrument may pay twice.", "type": "integer" }, "payment_instrument_id": { "type": "string", "format": "uuid" }, "amount": { "description": "What goes back, in the instrument's currency, IGTF included.", "allOf": [ { "$ref": "#/components/schemas/PosQuoteMoney" } ] }, "status": { "description": "refunded: a cash payment, paid back out of the drawer at once; pending_confirmation: any other rail, until its external reference is recorded; confirmed: once it is (MER-4979). A pending refund never blocks closing a Turno.", "type": "string", "enum": [ "refunded", "pending_confirmation", "confirmed" ] }, "external_reference": { "description": "The reference of the bank or wallet refund, trimmed and as typed; null until it is confirmed, so the void always answers null.", "type": "string", "example": "REF-123", "nullable": true }, "confirmed_at": { "description": "When it was confirmed, ISO 8601 in UTC; null until it is.", "type": "string", "format": "date-time", "example": "2026-10-29T16:30:00+00:00", "nullable": true }, "confirmed_by_user_id": { "description": "The authenticated user who confirmed it; null until someone does. A replay of the same reference by someone else keeps the original.", "type": "integer", "nullable": true } }, "type": "object" }, "CounterSaleRefundConfirmRequest": { "required": [ "external_reference" ], "properties": { "external_reference": { "description": "The reference of the bank or wallet refund: 1 to 100 characters, not blank, stored trimmed and as typed. It is the confirmation's idempotency key: the same reference again answers 200 and changes nothing; another answers 409.", "type": "string", "pattern": "\\S", "example": "REF-123", "maxLength": 100, "minLength": 1 } }, "type": "object" }, "PosQuoteRequest": { "required": [ "cash_register_id", "lines" ], "properties": { "cash_register_id": { "description": "The Caja that sells: it must be active and name an active pos Canal.", "type": "string", "format": "uuid" }, "currency": { "description": "The document currency. Omitted or null takes the currency of the Canal's default list, else USD.", "type": "string", "nullable": true, "enum": [ "USD", "VES" ] }, "buyer": { "description": "Who buys. Omitted or null is the Consumidor final without a document.", "required": [ "kind" ], "properties": { "kind": { "type": "string", "enum": [ "final_consumer", "client" ] }, "client_id": { "description": "Required with kind client, prohibited otherwise.", "type": "string", "format": "uuid", "nullable": true }, "document_type": { "description": "final_consumer only: V or E (cédula of 5 to 8 digits), J or G (RIF of 9 digits) or P (passport). Prohibited with kind client.", "type": "string", "nullable": true, "maxLength": 1 }, "document_number": { "description": "final_consumer only: the document's digits. Prohibited with kind client.", "type": "string", "nullable": true, "maxLength": 10 }, "name": { "description": "final_consumer only: up to 120 characters once spaces collapse. Prohibited with kind client.", "type": "string", "nullable": true, "maxLength": 255 } }, "type": "object", "nullable": true, "additionalProperties": false }, "lines": { "type": "array", "items": { "required": [ "item_id", "quantity" ], "properties": { "item_id": { "type": "string", "format": "uuid" }, "unit_id": { "description": "Omitted or null sells the Item's base unit.", "type": "string", "format": "uuid", "nullable": true }, "quantity": { "description": "Positive, up to 11 integer digits and 4 decimals.", "type": "string", "pattern": "^(?:[1-9]\\d{0,10}(?:\\.\\d{1,4})?|0\\.(?=\\d*[1-9])\\d{1,4})$", "example": "2" } }, "type": "object", "additionalProperties": false }, "maxItems": 200, "minItems": 1 }, "payments": { "description": "Optional preview of how the charge would settle them. Omitted or empty previews none.", "type": "array", "items": { "required": [ "payment_instrument_id", "amount" ], "properties": { "payment_instrument_id": { "description": "One of the Caja's rails.", "type": "string", "format": "uuid" }, "amount": { "description": "Positive, in the instrument's currency, up to 13 integer digits and 2 decimals.", "type": "string", "pattern": "^(?:[1-9]\\d{0,12}(?:\\.\\d{1,2})?|0\\.(?=\\d*[1-9])\\d{1,2})$", "example": "13.20" }, "reference": { "description": "Never required by a quote and never fingerprinted; the charge requires it on a rail that requires_reference.", "type": "string", "nullable": true, "maxLength": 100 } }, "type": "object", "additionalProperties": false }, "maxItems": 10 } }, "type": "object", "additionalProperties": false }, "WebOrderPosQuoteRequest": { "description": "A till quoting a Pedido web it holds (MER-5432, ADR 0362). It names the order as it saw it and how it pays: merchandise, buyer and currency come from the order, so lines, buyer and currency are refused (422) rather than compared. Sending a non-null web_order_id is what selects this body.", "required": [ "cash_register_id", "web_order_id", "expected_version", "claim_cycle_id" ], "properties": { "cash_register_id": { "description": "The Caja whose open Turno claimed the order.", "type": "string", "format": "uuid" }, "web_order_id": { "type": "string", "format": "uuid" }, "expected_version": { "description": "The version the till read; a buyer's rail change moves it.", "type": "integer", "minimum": 1 }, "claim_cycle_id": { "description": "The cycle of the claim this seller holds.", "type": "string", "format": "uuid" }, "payments": { "description": "What the till would collect, previewed as any tender; 0 to 10.", "type": "array", "items": { "required": [ "payment_instrument_id", "amount" ], "properties": { "payment_instrument_id": { "description": "One of the Caja's rails.", "type": "string", "format": "uuid" }, "amount": { "description": "Positive, in the instrument's currency, up to 13 integer digits and 2 decimals.", "type": "string", "pattern": "^(?:[1-9]\\d{0,12}(?:\\.\\d{1,2})?|0\\.(?=\\d*[1-9])\\d{1,2})$", "example": "1200.00" }, "reference": { "description": "Never required by a quote and never fingerprinted; the charge requires it on a rail that requires_reference.", "type": "string", "nullable": true, "maxLength": 100 } }, "type": "object", "additionalProperties": false }, "maxItems": 10 } }, "type": "object", "additionalProperties": false }, "PosQuoteWebOrder": { "description": "The Pedido web this quote charges (MER-5432). online_terms is what the buyer agreed online, to show apart from today's tender: the in-store payable is the ordinary rails[].settle_amount and totals.counterpart.", "required": [ "id", "display_id", "version", "claim_cycle_id", "online_terms" ], "properties": { "id": { "type": "string", "format": "uuid" }, "display_id": { "type": "string" }, "version": { "type": "integer" }, "claim_cycle_id": { "type": "string", "format": "uuid" }, "online_terms": { "$ref": "#/components/schemas/WebOrderPublicTerms" } }, "type": "object" }, "PosQuoteMoney": { "required": [ "amount", "currency" ], "properties": { "amount": { "type": "string", "example": "23.20" }, "currency": { "type": "string", "enum": [ "USD", "VES" ] } }, "type": "object" }, "PosQuoteLine": { "required": [ "index", "item_id", "item_name", "unit_id", "quantity", "status", "source", "unit_price", "price_fingerprint", "tax", "subtotal", "tax_amount", "total", "sellable_quantity", "out_of_stock", "blocked_by" ], "properties": { "index": { "type": "integer" }, "item_id": { "type": "string", "format": "uuid" }, "item_name": { "type": "string" }, "unit_id": { "type": "string", "format": "uuid" }, "quantity": { "type": "string", "example": "2.0000" }, "status": { "type": "string", "enum": [ "priced", "unpriced", "rate_unavailable", "rounds_to_zero" ] }, "source": { "type": "string", "nullable": true, "enum": [ "price_list", "base_price" ] }, "unit_price": { "description": "Per one unit of the line's unit, in the document currency; null unless priced.", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/PosQuoteMoney" } ] }, "price_fingerprint": { "description": "The price's Huella v2 (ADR 0272); null unless priced.", "type": "string", "pattern": "^[a-f0-9]{64}$", "nullable": true }, "tax": { "description": "The Item's «Impuesto de venta por defecto» while it is an active tax of the company; null otherwise (sales_tax_missing).", "required": [ "id", "percentage", "kind" ], "properties": { "id": { "type": "string", "format": "uuid" }, "percentage": { "type": "string", "example": "16.00" }, "kind": { "type": "string", "example": "vat_general" } }, "type": "object", "nullable": true }, "subtotal": { "description": "Null when blocked_by is not empty.", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/PosQuoteMoney" } ] }, "tax_amount": { "description": "Null when blocked_by is not empty.", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/PosQuoteMoney" } ] }, "total": { "description": "Null when blocked_by is not empty.", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/PosQuoteMoney" } ] }, "sellable_quantity": { "description": "The Disponible at the Canal's Location in the line's unit, truncated to 4 decimals; null for an Item never stocked. Never fingerprinted.", "type": "string", "example": "5.0000", "nullable": true }, "out_of_stock": { "description": "Whether every line of this Item together exceeds the Disponible. Never refused here; the charge decides under locks.", "type": "boolean" }, "blocked_by": { "description": "What keeps the line off an invoice; empty when the charge could write it.", "type": "array", "items": { "type": "string", "enum": [ "price_unavailable", "item_inactive", "sales_tax_missing", "revenue_account_missing", "accounting_center_missing" ] } } }, "type": "object" }, "PosQuotePayment": { "required": [ "index", "payment_instrument_id", "class", "amount", "reference", "applied", "rate", "igtf" ], "properties": { "index": { "type": "integer" }, "payment_instrument_id": { "type": "string", "format": "uuid" }, "class": { "type": "string", "example": "cash" }, "amount": { "description": "The money received, in the instrument's currency, IGTF included.", "allOf": [ { "$ref": "#/components/schemas/PosQuoteMoney" } ] }, "reference": { "type": "string", "nullable": true }, "applied": { "description": "The debt it settles in the document currency.", "allOf": [ { "$ref": "#/components/schemas/PosQuoteMoney" } ] }, "rate": { "description": "The official rate of its cash event.", "required": [ "value_date", "rate" ], "properties": { "value_date": { "type": "string", "format": "date" }, "rate": { "type": "string", "example": "36.50000000" } }, "type": "object" }, "igtf": { "description": "Its IGTF classification (ADR 0193). An unclassified one is only reported: the line settles its whole cash, and the charge refuses it with IGTF_SUBJECT_UNCLASSIFIED.", "required": [ "outcome", "percentage", "amount", "cause" ], "properties": { "outcome": { "type": "string", "enum": [ "not_evaluated", "not_perceived", "perceived", "unclassified" ] }, "percentage": { "type": "string", "example": "3.00", "nullable": true }, "amount": { "description": "The IGTF Perceived, in the instrument's currency.", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/PosQuoteMoney" } ] }, "cause": { "description": "Why it is unclassified.", "type": "string", "nullable": true } }, "type": "object" } }, "type": "object" }, "PosQuoteRail": { "required": [ "id", "name", "class", "currency", "requires_reference", "settle_amount" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "class": { "type": "string", "example": "cash" }, "currency": { "type": "string", "enum": [ "USD", "VES" ] }, "requires_reference": { "type": "boolean" }, "settle_amount": { "description": "What the till would type through this rail, in its own currency and IGTF included, so that with the payments sent the settlement settles (MER-5157): what remains (the total when no payment was sent) at the rate this rail's cash event takes, plus the IGTF its classification adds, verified by quoting it with the payments sent through the charge's own check, one cent at a time for at most three cents. A bolívar rail of a document not in bolívares, whose quote has a bolívar counterpart, offers instead the invoice's bolívares (totals.counterpart.total) less what the payments sent cover, plus its IGTF, when that settles, and otherwise the amount at the rate; a bolívar document, a web order, a company with both books in dollars and a day with no document rate keep the rate. Null when nothing remains (it settles, or remaining is negative), when the rail cannot be valued without an official rate (OFFICIAL_RATE_STALE, OFFICIAL_RATE_NOT_AVAILABLE; computing it never answers 422), when its IGTF is unclassifiable, when it is no longer a rail of the Caja, or when no amount within those cents settles, as for a dollar rail against a bolívar total that one dollar cent overshoots. Never fingerprinted.", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/PosQuoteMoney" } ] } }, "type": "object" }, "PosQuote": { "required": [ "date", "cash_register_id", "sales_channel_id", "location_id", "currency", "price_list_id", "rate", "buyer", "lines", "totals", "rails", "payments", "settlement", "quote_fingerprint", "unidentified_buyer_after_legal_date" ], "properties": { "date": { "description": "The company's day.", "type": "string", "format": "date" }, "cash_register_id": { "type": "string", "format": "uuid" }, "sales_channel_id": { "type": "string", "format": "uuid" }, "location_id": { "type": "string", "format": "uuid" }, "currency": { "type": "string", "enum": [ "USD", "VES" ] }, "price_list_id": { "type": "string", "format": "uuid", "nullable": true }, "rate": { "description": "The document rate of the day (ADR 0143) on the leg that converts; null when none applies or nothing converts.", "required": [ "value_date", "rate", "from", "to" ], "properties": { "value_date": { "type": "string", "format": "date" }, "rate": { "type": "string", "example": "36.50000000" }, "from": { "type": "string", "enum": [ "USD", "VES" ] }, "to": { "type": "string", "enum": [ "USD", "VES" ] } }, "type": "object", "nullable": true }, "buyer": { "required": [ "kind", "client_id", "document_type", "document_number", "name" ], "properties": { "kind": { "type": "string", "enum": [ "final_consumer", "client" ] }, "client_id": { "type": "string", "format": "uuid", "nullable": true }, "document_type": { "type": "string", "nullable": true }, "document_number": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true } }, "type": "object" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/PosQuoteLine" } }, "totals": { "description": "The lines an invoice could hold, and their counterpart as approving the invoice freezes it (ADR 0160); counterpart is null without a document rate.", "required": [ "subtotal", "taxes", "total", "counterpart" ], "properties": { "subtotal": { "allOf": [ { "$ref": "#/components/schemas/PosQuoteMoney" } ] }, "taxes": { "allOf": [ { "$ref": "#/components/schemas/PosQuoteMoney" } ] }, "total": { "allOf": [ { "$ref": "#/components/schemas/PosQuoteMoney" } ] }, "counterpart": { "required": [ "currency", "subtotal", "taxes", "total" ], "properties": { "currency": { "type": "string", "enum": [ "USD", "VES" ] }, "subtotal": { "type": "string", "example": "730.00" }, "taxes": { "type": "string", "example": "116.80" }, "total": { "type": "string", "example": "846.80" } }, "type": "object", "nullable": true } }, "type": "object" }, "rails": { "description": "The Caja's own cash instruments, then the company's other active instruments, in USD or VES.", "type": "array", "items": { "$ref": "#/components/schemas/PosQuoteRail" } }, "payments": { "type": "array", "items": { "$ref": "#/components/schemas/PosQuotePayment" } }, "settlement": { "description": "Null when no payment was sent. settles is the charge's own check: the debt the payments derive equals the total, or is within one cent per converting payment. When it settles, remaining is 0.00 and rounding is what the tolerance absorbed; otherwise remaining is what is still to pay, negative when the payments derive more.", "required": [ "total", "applied", "remaining", "rounding", "settles" ], "properties": { "total": { "allOf": [ { "$ref": "#/components/schemas/PosQuoteMoney" } ] }, "applied": { "allOf": [ { "$ref": "#/components/schemas/PosQuoteMoney" } ] }, "remaining": { "allOf": [ { "$ref": "#/components/schemas/PosQuoteMoney" } ] }, "rounding": { "allOf": [ { "$ref": "#/components/schemas/PosQuoteMoney" } ] }, "settles": { "type": "boolean" } }, "type": "object", "nullable": true }, "quote_fingerprint": { "description": "What the charge compares when it quotes again; never covers references, the buyer's document or the Disponible.", "type": "string", "pattern": "^[a-f0-9]{64}$" }, "unidentified_buyer_after_legal_date": { "description": "A non-blocking warning (ADR 0352, MER-5756). True when the invoice the charge would write goes to the company's Consumidor final, date is on or after 2027-04-19 (PA SNAT/2026/00093 art. 8.6), and the buyer lacks a name or a RIF, cédula or passport. It is never fingerprinted and charging never refuses for it.", "type": "boolean" }, "web_order": { "description": "Only on a quote of a Pedido web. Its lines then carry status priced with a null source and price_fingerprint, price_list_id is null, and buyer names no Client: kind client with every other member null.", "allOf": [ { "$ref": "#/components/schemas/PosQuoteWebOrder" } ] } }, "type": "object" }, "PosQuoteProblem": { "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "error_code": { "type": "string", "nullable": true }, "errors": { "description": "Request validation messages by field.", "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "reason": { "description": "With counter_sale_cash_register_not_selling.", "type": "string", "enum": [ "cash_register_inactive", "no_sales_channel", "sales_channel_not_found", "sales_channel_inactive", "sales_channel_not_pos" ] }, "lines": { "description": "With counter_sale_item_not_found: each line naming an unknown Item.", "type": "array", "items": { "required": [ "index", "item_id" ], "properties": { "index": { "type": "integer" }, "item_id": { "type": "string" } }, "type": "object" } }, "payments": { "description": "With counter_sale_payment_instrument_not_a_rail: each payment off the Caja's rails.", "type": "array", "items": { "required": [ "index", "payment_instrument_id" ], "properties": { "index": { "type": "integer" }, "payment_instrument_id": { "type": "string" } }, "type": "object" } }, "client_id": { "description": "With counter_sale_client_not_found.", "type": "string" }, "missing": { "description": "With client_fiscal_identity_incomplete: what the Pedido web's Client lacks, and never who it is.", "type": "array", "items": { "type": "string" } }, "field_errors": { "description": "With sale_price_line_unit_not_of_item: messages by lines.N.unit_id.", "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" }, "SalesCreditApplicationProblem": { "description": "Controller validation and domain errors. Validation has a null error_code and an errors object mapping field names to messages; domain refusals have an error_code and null errors.", "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "error_code": { "type": "string", "nullable": true }, "errors": { "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "cash_register_id": { "description": "With cash_shift_not_open.", "type": "string", "format": "uuid" } }, "type": "object" }, "SalesCreditApplicationAccountingConfigurationError": { "description": "The entry of the application cannot post: OFFICIAL_RATE_STALE, OFFICIAL_RATE_NOT_AVAILABLE, RECEIVABLE_ACCOUNT_MISSING, RECEIVABLE_ACCOUNT_INACTIVE, RECEIVABLE_CENTER_MISSING, EXCHANGE_POSTING_ACCOUNT_MISSING, ACCOUNTING_PERIOD_CLOSED or LEDGER_FLOW_NOT_PARALLEL_CURRENCY_READY.", "required": [ "error", "missing" ], "properties": { "error": { "type": "string", "enum": [ "accounting_configuration_incomplete" ] }, "missing": { "type": "array", "items": { "required": [ "reason_code", "subject_type", "subject_id", "human_message", "details" ], "properties": { "reason_code": { "type": "string", "example": "OFFICIAL_RATE_STALE" }, "subject_type": { "type": "string" }, "subject_id": { "type": "string" }, "human_message": { "type": "string" }, "details": { "type": "array", "items": { "type": "string" } } }, "type": "object" } } }, "type": "object" }, "SalesCreditApplicationDifference": { "description": "One per-book difference by leg and cause, signed from the company's side: positive is a realized gain, negative a loss. An application recorded at its note's approval only has rounding on the invoice leg.", "required": [ "leg", "book", "cause", "amount", "currency" ], "properties": { "leg": { "type": "string", "enum": [ "invoice", "source" ] }, "book": { "type": "string", "enum": [ "functional", "reporting" ] }, "cause": { "type": "string", "enum": [ "debt_currency", "rounding" ] }, "amount": { "type": "string", "example": "-1600.00" }, "currency": { "type": "string", "example": "VES" } }, "type": "object" }, "SalesCreditApplication": { "description": "A Sales Credit Application: what one credit source relieved from one target of its client. Its source is a Sales Credit Note (credit_note): either the application its approval recorded on its origin (applied_at_approval true: dated at the note's emission, no Rate Snapshot of its own, never revertible on its own), or one of its Customer Credit applied to another invoice (MER-3277); or a customer advance, a collection of kind advance (collection, MER-3279). Its target is a sales invoice, or a credit balance refund («devolución de saldo a favor», MER-3280): target.type collection with kind refund, the note's Customer Credit or the customer advance (MER-3641) paid out in cash. For a refund, invoice_relieved holds the official value of the units refunded, its only differences are the source leg's debt_currency (the cash leg's treasury_currency lives on the refund, GET /sales/collections/{id}), and it is never revertible on its own (cancel the refund; reverting it answers 422 application_not_revertible). Every application but an approval's has the Rate Snapshot its units were valued at. Both legs in the three books and the differences its entry posted.", "required": [ "id", "source", "target", "applied_at_approval", "date", "source_units", "source_currency", "rate_snapshot", "invoice_relieved", "source_relieved", "differences", "reverted_at", "revertible" ], "properties": { "id": { "type": "string", "format": "uuid" }, "source": { "required": [ "type", "id", "code" ], "properties": { "type": { "type": "string", "enum": [ "credit_note", "collection" ] }, "id": { "description": "The note, or the advance's collection.", "type": "string", "format": "uuid" }, "code": { "description": "The note's code, or the advance's; null only when the source cannot be read.", "type": "string", "example": "NC2600001", "nullable": true } }, "type": "object" }, "target": { "required": [ "type", "id", "code", "kind" ], "properties": { "type": { "description": "collection: a credit balance refund (MER-3280).", "type": "string", "enum": [ "sales_invoice", "collection" ] }, "id": { "type": "string", "format": "uuid" }, "code": { "description": "The invoice's code, or the refund's (COB…); null only when it cannot be read.", "type": "string", "example": "INV2600012", "nullable": true }, "kind": { "description": "The invoice's kind, or refund for a credit balance refund; null only when it cannot be read.", "type": "string", "nullable": true, "enum": [ "regular", "opening", "debit_note", "refund" ] } }, "type": "object" }, "applied_at_approval": { "description": "Recorded by the note's approval on its origin.", "type": "boolean" }, "date": { "description": "The application's date; the note's emission date for an application recorded at approval.", "type": "string", "format": "date" }, "source_units": { "type": "string", "example": "80.00" }, "source_currency": { "type": "string", "example": "USD" }, "rate_snapshot": { "description": "Null for an application recorded at approval.", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/CashEventRateSnapshotView" } ] }, "invoice_relieved": { "description": "What the invoice gave up; for a refund, the units refunded at their official value less their rounding.", "allOf": [ { "$ref": "#/components/schemas/RelievedAmounts" } ] }, "source_relieved": { "$ref": "#/components/schemas/RelievedAmounts" }, "differences": { "type": "array", "items": { "$ref": "#/components/schemas/SalesCreditApplicationDifference" } }, "reverted_at": { "type": "string", "format": "date-time", "nullable": true }, "revertible": { "description": "Whether the application can still be unapplied on its own; the caller still needs backoffice.sales.collections.apply-credit.", "type": "boolean" } }, "type": "object" }, "SalesCreditApplicationList": { "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SalesCreditApplication" } } }, "type": "object" }, "SalesCreditApplicationPreview": { "description": "What applying the note's Customer Credit or the customer advance would record, by the same calculator, rate rule and readiness as applying, with nothing written.", "required": [ "source", "target", "date", "source_units", "source_currency", "source_available", "units_to_settle_in_full", "derived_debt", "debt_currency", "settles_in_full", "rate_snapshot", "invoice_relieved", "invoice_open_after", "source_relieved", "source_open_after", "differences" ], "properties": { "source": { "required": [ "type", "id", "code" ], "properties": { "type": { "type": "string", "enum": [ "credit_note", "collection" ] }, "id": { "type": "string", "format": "uuid" }, "code": { "type": "string", "example": "NC2600001" } }, "type": "object" }, "target": { "required": [ "type", "id", "code", "kind" ], "properties": { "type": { "type": "string", "enum": [ "sales_invoice" ] }, "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "kind": { "type": "string", "enum": [ "regular" ] } }, "type": "object" }, "date": { "type": "string", "format": "date" }, "source_units": { "description": "The units previewed: those asked, or the ones proposed when none were.", "type": "string", "example": "80.00" }, "source_currency": { "type": "string", "example": "USD" }, "source_available": { "description": "What the source holds now: the Customer Credit the note keeps, or the advance's balance.", "type": "string", "example": "80.00" }, "units_to_settle_in_full": { "description": "The units that settle the invoice's open balance in full at this snapshot.", "type": "string", "example": "100.00" }, "derived_debt": { "type": "string", "example": "9600.00" }, "debt_currency": { "type": "string", "example": "VES" }, "settles_in_full": { "type": "boolean" }, "rate_snapshot": { "$ref": "#/components/schemas/CashEventRateSnapshotView" }, "invoice_relieved": { "$ref": "#/components/schemas/RelievedAmounts" }, "invoice_open_after": { "$ref": "#/components/schemas/RelievedAmounts" }, "source_relieved": { "$ref": "#/components/schemas/RelievedAmounts" }, "source_open_after": { "$ref": "#/components/schemas/RelievedAmounts" }, "differences": { "type": "array", "items": { "$ref": "#/components/schemas/SalesCreditApplicationDifference" } } }, "type": "object" }, "CustomerCreditRefundDifference": { "description": "One per-book difference of a credit balance refund, signed from the company's side: positive is a realized gain, negative a loss. The source leg's debt_currency is what the source's Carrying Amount, a note's or an Advance's, and the official value at the refund's rate disagree on; its rounding is what a source emptied within the tolerance gave up beyond what the money derives, and any cents of the conversion (MER-5688); the treasury leg's treasury_currency is what the cash's Carrying Amount and its official value disagree on.", "required": [ "leg", "book", "cause", "amount", "currency" ], "properties": { "leg": { "type": "string", "enum": [ "source", "treasury" ] }, "book": { "type": "string", "enum": [ "functional", "reporting" ] }, "cause": { "type": "string", "enum": [ "debt_currency", "rounding", "treasury_currency" ] }, "amount": { "type": "string", "example": "-1600.00" }, "currency": { "type": "string", "example": "VES" } }, "type": "object" }, "CustomerCreditRefundPreview": { "description": "What refunding one credit source in cash through one instrument would record, by the same calculator, rate rule and readiness as registering the refund, with nothing locked or written: a credit note's Customer Credit (MER-3280, GET /sales/credit-notes/{id}/refund-preview) or a customer Advance (MER-3641, GET /sales/collections/{id}/refund-preview). Through an instrument in another currency it answers what to send (MER-5688): treasury.units is the money, amount_collected and the method line's amountCollected, in treasury.currency; source_units is what credit_applications[].source_units states.", "required": [ "source", "date", "source_units", "source_currency", "source_available", "rate_snapshot", "source_relieved", "source_open_after", "official_value", "treasury", "differences", "settles_in_full" ], "properties": { "source": { "description": "The credit source previewed (MER-3641).", "required": [ "type", "id", "code" ], "properties": { "type": { "description": "credit_note for a note's Customer Credit, collection for a customer Advance.", "type": "string", "enum": [ "credit_note", "collection" ] }, "id": { "type": "string", "format": "uuid" }, "code": { "type": "string", "example": "NC2600001" } }, "type": "object" }, "credit_note": { "description": "Deprecated in favour of source (MER-3641): present only on GET /sales/credit-notes/{id}/refund-preview, naming the same note.", "required": [ "id", "code" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string", "example": "NC2600001" } }, "type": "object", "deprecated": true }, "date": { "type": "string", "format": "date" }, "source_units": { "description": "The units previewed: those asked, or the source's whole balance. Through an instrument in another currency they may differ from those asked: exactly what the money derives, or the whole balance when it derives that within the tolerance.", "type": "string", "example": "80.00" }, "source_currency": { "type": "string", "example": "USD" }, "source_available": { "description": "What the source holds now: a note's Customer Credit or an Advance's balance.", "type": "string", "example": "80.00" }, "rate_snapshot": { "$ref": "#/components/schemas/CashEventRateSnapshotView" }, "source_relieved": { "description": "What the source gives up, at its Carrying Amount.", "allOf": [ { "$ref": "#/components/schemas/RelievedAmounts" } ] }, "source_open_after": { "description": "What the source keeps afterwards.", "allOf": [ { "$ref": "#/components/schemas/RelievedAmounts" } ] }, "official_value": { "description": "The units paid out, at their official value less their rounding.", "allOf": [ { "$ref": "#/components/schemas/RelievedAmounts" } ] }, "treasury": { "required": [ "instrument_id", "accounting_account_id", "units", "currency", "posted" ], "properties": { "instrument_id": { "type": "string", "format": "uuid" }, "accounting_account_id": { "type": "string", "format": "uuid" }, "units": { "description": "The money, in the instrument's currency.", "type": "string", "example": "80.00" }, "currency": { "description": "The instrument's currency.", "type": "string", "example": "USD" }, "posted": { "description": "The cash leg at its Carrying Amount (ADR 0197).", "required": [ "functional", "reporting", "functional_currency", "reporting_currency" ], "properties": { "functional": { "type": "string", "example": "8800.00" }, "reporting": { "type": "string", "example": "80.00" }, "functional_currency": { "type": "string", "example": "VES" }, "reporting_currency": { "type": "string", "example": "USD" } }, "type": "object" } }, "type": "object" }, "differences": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerCreditRefundDifference" } }, "settles_in_full": { "description": "Whether the refund empties the source.", "type": "boolean" } }, "type": "object" }, "ClientCreditBalances": { "description": "The Customer Credit a client's credit notes keep, per currency and never summed across currencies; balances is empty when there is none. credit_notes is empty for a caller without backoffice.sales.credit-notes.view; the balance and its reporting equivalent stay. Beside it, advance_balances lists the client's open customer advances per currency (MER-3279), never summed with the Customer Credit: an advance is not «saldo a favor». It is empty when there is none. Each currency's reporting_balance is its equivalent in reporting_currency (MER-3281): the stored reporting-book Carrying Amount of its documents summed within that currency, a book value never converted at today's rate.", "required": [ "client_id", "reporting_currency", "balances", "advance_balances" ], "properties": { "client_id": { "type": "string", "format": "uuid" }, "reporting_currency": { "description": "The company's reporting currency, in which every reporting_balance is stated.", "type": "string", "example": "USD" }, "balances": { "type": "array", "items": { "required": [ "currency", "balance", "reporting_balance", "credit_notes" ], "properties": { "currency": { "type": "string", "example": "VES" }, "balance": { "type": "string", "example": "1000.00" }, "reporting_balance": { "description": "The stored reporting-book Carrying Amount of the currency's notes, in reporting_currency; never a conversion at today's rate.", "type": "string", "example": "8.33" }, "credit_notes": { "type": "array", "items": { "required": [ "id", "code", "emission_date", "balance" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string", "example": "NC2600001" }, "emission_date": { "type": "string", "format": "date" }, "balance": { "type": "string", "example": "80.00" } }, "type": "object" } } }, "type": "object" } }, "advance_balances": { "type": "array", "items": { "required": [ "currency", "balance", "reporting_balance", "advances" ], "properties": { "currency": { "type": "string", "example": "USD" }, "balance": { "type": "string", "example": "200.00" }, "reporting_balance": { "description": "The stored reporting-book Carrying Amount of the currency's advances, in reporting_currency; never a conversion at today's rate.", "type": "string", "example": "200.00" }, "advances": { "type": "array", "items": { "required": [ "id", "code", "date_collection", "balance" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string", "example": "COB00043" }, "date_collection": { "description": "The earliest date an application of it may take.", "type": "string", "format": "date" }, "balance": { "type": "string", "example": "200.00" } }, "type": "object" } } }, "type": "object" } } }, "type": "object" }, "SalesCreditNoteLineInput": { "description": "One line of a Sales Credit Note. A unit_return or amount_rebate credits one origin invoice line (required origin_sales_invoice_item_id). An opening_rebate credits an Opening Document with no origin line: it states category, item, unit, tax, center, account and a positive base amount; the server stamps item_name and the tax rate/kind from the catalog (MER-4638).", "required": [ "id", "line_type" ], "properties": { "id": { "description": "Client-generated line id, unique within the note; a repeated request must repeat it.", "type": "string", "format": "uuid", "example": "0199a000-0000-7000-8000-0000000001a1" }, "origin_sales_invoice_item_id": { "description": "Required for unit_return and amount_rebate; prohibited for opening_rebate. Each origin line at most once per note.", "type": "string", "format": "uuid", "example": "0199a000-0000-7000-8000-0000000000b1", "nullable": true }, "line_type": { "type": "string", "example": "unit_return", "enum": [ "unit_return", "amount_rebate", "opening_rebate" ] }, "units": { "description": "Required for a unit_return and prohibited otherwise: the units given back, greater than zero, at most 4 decimals.", "type": "string", "pattern": "^(?!0+(?:\\.0{1,4})?$)\\d{1,11}(?:\\.\\d{1,4})?$", "example": "2" }, "amount": { "description": "Required for amount_rebate and opening_rebate; prohibited for unit_return. Positive base in the origin currency, at most 2 decimals.", "type": "string", "pattern": "^(?!0+(?:\\.0{1,2})?$)\\d{1,13}(?:\\.\\d{1,2})?$", "example": "5.00" }, "category_id": { "description": "Required for opening_rebate; prohibited otherwise.", "type": "string", "format": "uuid" }, "item_id": { "description": "Required for opening_rebate; prohibited otherwise.", "type": "string", "format": "uuid" }, "unit_id": { "description": "Required for opening_rebate; prohibited otherwise.", "type": "string", "format": "uuid" }, "tax_id": { "description": "Required for opening_rebate; prohibited otherwise. Rate and kind come from the active catalog tax.", "type": "string", "format": "uuid" }, "accounting_center_id": { "description": "Required for opening_rebate; prohibited otherwise.", "type": "string", "format": "uuid" }, "accounting_account_id": { "description": "Required for opening_rebate; prohibited otherwise.", "type": "string", "format": "uuid" } }, "type": "object", "additionalProperties": false }, "SalesCreditNoteRegistered": { "required": [ "sales_credit_note_id", "code" ], "properties": { "sales_credit_note_id": { "type": "string", "format": "uuid" }, "code": { "description": "The note's internal code: NC, the two-digit year and its own five-digit correlative.", "type": "string", "example": "NC2600001" } }, "type": "object" }, "SalesDocumentControlNumberConflict": { "description": "The control number already belongs to another non-cancelled invoice or note of this company: invoices and notes share one control series.", "required": [ "title", "status", "detail", "error_code", "existing_code", "existing_kind" ], "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "detail": { "type": "string", "example": "El número de control ya está registrado en la factura de venta INV2600007" }, "error_code": { "type": "string", "enum": [ "sales_invoice_control_number_already_registered" ] }, "existing_code": { "description": "The code of the document that holds the control number, or null when a concurrent commit leaves the failure path unable to name it.", "type": "string", "example": "INV2600007", "nullable": true }, "existing_kind": { "description": "The kind of that document. Null exactly when existing_code is null.", "type": "string", "example": "regular", "nullable": true, "enum": [ "regular", "opening", "credit_note", "debit_note", "advance" ] } }, "type": "object" }, "SalesCreditNoteLineCapExceeded": { "description": "A line asks for more than its origin line still has to credit after the approved credit notes.", "required": [ "error", "detail", "line_id", "available_units", "available_amount", "currency" ], "properties": { "error": { "type": "string", "enum": [ "line_credit_cap_exceeded" ] }, "detail": { "type": "string" }, "line_id": { "description": "The origin invoice line whose cap was exceeded.", "type": "string", "format": "uuid" }, "available_units": { "type": "string", "example": "2.0000" }, "available_amount": { "type": "string", "example": "20.00" }, "currency": { "type": "string", "example": "USD" } }, "type": "object" }, "SalesCreditNoteApproved": { "description": "What the approval did: how much of the note applied to its origin's open balance, and the Customer Credit it keeps, in the note's currency.", "required": [ "sales_credit_note_id", "status", "currency", "applied_amount", "customer_credit", "credit_application_id" ], "properties": { "sales_credit_note_id": { "type": "string", "format": "uuid" }, "status": { "description": "applied when nothing is left as Customer Credit.", "type": "string", "enum": [ "with_customer_credit", "applied" ] }, "currency": { "type": "string", "example": "USD" }, "applied_amount": { "description": "What the note relieved from its origin; 0.00 when the origin owed nothing.", "type": "string", "example": "11.60" }, "customer_credit": { "description": "What the note keeps as Customer Credit.", "type": "string", "example": "0.00" }, "credit_application_id": { "description": "The Credit Application that relieved the origin; null when nothing applied.", "type": "string", "format": "uuid", "nullable": true } }, "type": "object" }, "SalesCreditNoteCancelled": { "description": "What the cancellation did: what this call gave back to the invoices the note's Credit Applications relieved, in the note's currency.", "required": [ "sales_credit_note_id", "status", "currency", "restored_amount" ], "properties": { "sales_credit_note_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "cancelled" ] }, "currency": { "type": "string", "example": "USD" }, "restored_amount": { "description": "What the origin owes again; 0.00 for a draft, for a note that applied nothing, and when the note was already cancelled.", "type": "string", "example": "11.60" } }, "type": "object" }, "SalesDebitNoteLineInput": { "description": "One line of a Sales Debit Note. A linked_increase raises one line of its origin invoice, at most once per note: it states `units` (valued at the origin line's own invoiced net unit price) or `amount`, never both, and inherits the origin line's item, tax, center and revenue account. A new_concept charges something the origin never had: it brings its own item, unit, quantity, unit price, tax, center and revenue account, and is priced like an invoice line with no discount. A line worth nothing is refused. A note holds lines of one type, because its rate follows it: linked increases keep the origin's rate and new concepts take the rate of the note's emission day.", "required": [ "id", "line_type" ], "properties": { "id": { "description": "Client-generated line id, unique within the note; a repeated request must repeat it.", "type": "string", "format": "uuid", "example": "0199a000-0000-7000-8000-0000000003a1" }, "line_type": { "type": "string", "example": "new_concept", "enum": [ "linked_increase", "new_concept" ] }, "origin_sales_invoice_item_id": { "description": "linked_increase only, required: the origin invoice line it raises; each origin line at most once per note.", "type": "string", "format": "uuid" }, "units": { "description": "linked_increase only: the units added, greater than zero, at most 4 decimals. Prohibits `amount`; stating neither answers 422 sales_debit_note_linked_increase_without_increase.", "type": "string", "pattern": "^(?!0+(?:\\.0{1,4})?$)\\d{1,11}(?:\\.\\d{1,4})?$", "example": "2" }, "amount": { "description": "linked_increase only: the amount added in the origin's currency, greater than zero, at most 2 decimals.", "type": "string", "pattern": "^(?!0+(?:\\.0{1,2})?$)\\d{1,13}(?:\\.\\d{1,2})?$", "example": "5.00" }, "category_id": { "description": "new_concept only.", "type": "string", "format": "uuid", "nullable": true }, "item_id": { "description": "new_concept only, required.", "type": "string", "format": "uuid" }, "item_name": { "description": "new_concept only.", "type": "string", "nullable": true, "maxLength": 255 }, "unit_id": { "description": "new_concept only, required.", "type": "string", "format": "uuid" }, "quantity": { "description": "new_concept only, required: greater than zero, at most 4 decimals.", "type": "string", "example": "1" }, "unit_price": { "description": "new_concept only, required: at most 2 decimals.", "type": "string", "example": "5.00" }, "tax_id": { "description": "new_concept only, required: an active tax of the catalog whose rate is tax_percentage (422 sales_invoice_tax_selection_invalid otherwise).", "type": "string", "format": "uuid" }, "tax_percentage": { "description": "new_concept only, required.", "type": "string", "example": "16.00" }, "accounting_center_id": { "description": "new_concept only, required.", "type": "string", "format": "uuid" }, "accounting_account_id": { "description": "new_concept only, required: the revenue account the line posts to.", "type": "string", "format": "uuid" } }, "type": "object", "additionalProperties": false }, "SalesDebitNoteLine": { "required": [ "id", "line_type", "origin_sales_invoice_item_id", "units", "amount", "quantity", "unit_price", "category_id", "item_id", "item_name", "unit_id", "tax_id", "tax_percentage", "tax_kind", "accounting_center_id", "accounting_account_id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "line_type": { "type": "string", "enum": [ "linked_increase", "new_concept" ] }, "origin_sales_invoice_item_id": { "description": "Null for a new_concept.", "type": "string", "format": "uuid", "nullable": true }, "units": { "description": "The units a linked_increase adds; null when it states an amount, and for a new_concept.", "type": "string", "example": "2.0000", "nullable": true }, "amount": { "description": "What the line adds before tax.", "type": "string", "example": "5.00" }, "quantity": { "description": "new_concept only.", "type": "string", "example": "1.0000", "nullable": true }, "unit_price": { "description": "new_concept only.", "type": "string", "example": "5.00", "nullable": true }, "category_id": { "type": "string" }, "item_id": { "type": "string", "format": "uuid" }, "item_name": { "type": "string" }, "unit_id": { "type": "string", "format": "uuid" }, "tax_id": { "type": "string", "format": "uuid" }, "tax_percentage": { "type": "string", "example": "16.00" }, "tax_kind": { "type": "string", "example": "vat_general" }, "accounting_center_id": { "type": "string", "format": "uuid" }, "accounting_account_id": { "type": "string", "format": "uuid" } }, "type": "object" }, "SalesDebitNoteRegistered": { "required": [ "sales_debit_note_id", "code" ], "properties": { "sales_debit_note_id": { "type": "string", "format": "uuid" }, "code": { "description": "The note's internal code: ND, the two-digit year and its own five-digit correlative.", "type": "string", "example": "ND2600001" } }, "type": "object" }, "SalesDebitNoteCancelled": { "description": "What the cancellation did: what this call reversed of the note's approved entry, in the note's currency.", "required": [ "sales_debit_note_id", "status", "currency", "reversed_amount" ], "properties": { "sales_debit_note_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "cancelled" ] }, "currency": { "type": "string", "example": "USD" }, "reversed_amount": { "description": "The note's total for an approved note; 0.00 for a draft and when the note was already cancelled.", "type": "string", "example": "5.80" } }, "type": "object" }, "OpportunityEvidence": { "required": [ "inbound_event_id", "occurred_at", "channel" ], "properties": { "inbound_event_id": { "type": "string", "maxLength": 200, "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "channel": { "type": "string", "enum": [ "WHATSAPP" ] } }, "type": "object", "additionalProperties": false }, "OpportunityOpenRequest": { "required": [ "contact_id", "need", "origin_channel", "services", "package_agreement", "evidence" ], "properties": { "contact_id": { "type": "string", "format": "uuid" }, "need": { "type": "string", "maxLength": 2000, "minLength": 1 }, "origin_channel": { "type": "string", "enum": [ "WHATSAPP", "LANDING", "OTHER" ] }, "services": { "type": "array", "items": { "type": "string", "maxLength": 120, "minLength": 1 }, "maxItems": 20 }, "package_agreement": { "type": "boolean" }, "journey_notes": { "type": "string", "nullable": true, "maxLength": 4000 }, "evidence": { "$ref": "#/components/schemas/OpportunityEvidence" } }, "type": "object", "additionalProperties": false }, "OpportunityUpdateRequest": { "required": [ "expected_version", "evidence" ], "properties": { "expected_version": { "type": "integer", "minimum": 1 }, "need": { "type": "string", "maxLength": 2000, "minLength": 1 }, "origin_channel": { "type": "string", "enum": [ "WHATSAPP", "LANDING", "OTHER" ] }, "services": { "type": "array", "items": { "type": "string", "maxLength": 120, "minLength": 1 }, "maxItems": 20 }, "package_agreement": { "type": "boolean" }, "journey_notes": { "type": "string", "nullable": true, "maxLength": 4000 }, "evidence": { "$ref": "#/components/schemas/OpportunityEvidence" } }, "type": "object", "additionalProperties": false }, "OpportunityView": { "required": [ "id", "contact_id", "status", "need", "origin_channel", "services", "package_agreement", "version", "opened_effect_id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "contact_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "OPEN" ] }, "need": { "type": "string" }, "origin_channel": { "type": "string", "enum": [ "WHATSAPP", "LANDING", "OTHER" ] }, "services": { "type": "array", "items": { "type": "string" } }, "package_agreement": { "type": "boolean" }, "journey_notes": { "type": "string", "nullable": true }, "version": { "type": "integer", "minimum": 1 }, "opened_effect_id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "nullable": true }, "updated_at": { "type": "string", "format": "date-time", "nullable": true } }, "type": "object" }, "OpportunitySummary": { "required": [ "id", "need", "origin_channel", "services", "package_agreement", "version" ], "properties": { "id": { "type": "string", "format": "uuid" }, "need": { "type": "string", "maxLength": 200 }, "origin_channel": { "type": "string", "enum": [ "WHATSAPP", "LANDING", "OTHER" ] }, "services": { "type": "array", "items": { "type": "string" } }, "package_agreement": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time", "nullable": true }, "version": { "type": "integer", "minimum": 1 } }, "type": "object" }, "OpportunityList": { "required": [ "opportunities" ], "properties": { "opportunities": { "type": "array", "items": { "$ref": "#/components/schemas/OpportunitySummary" } } }, "type": "object" }, "OpportunityEffect": { "required": [ "effect_id", "request_hash", "state", "original_result", "failure_code", "http_status" ], "properties": { "effect_id": { "type": "string", "format": "uuid" }, "request_hash": { "type": "string", "maxLength": 64, "minLength": 64 }, "state": { "type": "string", "enum": [ "PENDING", "APPLIED", "FAILED" ] }, "original_result": { "properties": { "opportunity": { "$ref": "#/components/schemas/OpportunityView" }, "created": { "type": "boolean" } }, "type": "object", "nullable": true }, "failure_code": { "type": "string", "nullable": true }, "http_status": { "type": "integer", "nullable": true } }, "type": "object" }, "OpportunityProblem": { "required": [ "title", "status", "detail", "error_code" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "error_code": { "type": "string", "nullable": true }, "errors": { "type": "object", "nullable": true } }, "type": "object" }, "PotentialCustomersSearchRequest": { "description": "Sensitive potential-customer search body. Every property is optional, so the empty object `{}` is a valid request meaning the unfiltered tenant work queue. The tenant is taken from the path only: `companyId` and `company_id` are not properties here and are rejected like any other unsupported property. `search` matches name OR phone OR email as one group; `name`, `phone`, and `email` are individual predicates ANDed with each other, with `search`, and with the structural and temporal filters.", "properties": { "view": { "description": "Active applies the five open pipeline stages before pagination; omitted preserves all stages.", "type": "string", "default": "all", "enum": [ "active", "all" ] }, "label_ids": { "description": "Union within labels, intersection with other filters; unknown or foreign IDs match nothing.", "type": "array", "items": { "type": "string", "format": "uuid" }, "uniqueItems": true }, "page": { "description": "Defaults to 1.", "type": "integer", "minimum": 1 }, "per_page": { "description": "Defaults to 20.", "type": "integer", "maximum": 100, "minimum": 1 }, "status": { "description": "OR within the category.", "type": "array", "items": { "type": "string", "enum": [ "pre_qualified", "contacting", "discovery", "qualified", "proposal", "converted", "lost", "nurture" ] }, "minItems": 1, "uniqueItems": true }, "source": { "description": "OR within the category.", "type": "array", "items": { "type": "string", "enum": [ "social_media", "manager", "secretary", "website", "referral", "inbound_call" ] }, "minItems": 1, "uniqueItems": true }, "assigned_salesperson_id": { "description": "Every salesperson must belong to the path tenant.", "type": "array", "items": { "type": "integer", "minimum": 1 }, "minItems": 1, "uniqueItems": true }, "urgency": { "type": "string", "enum": [ "overdue", "today", "upcoming", "without_next_action" ] }, "created_from": { "description": "Inclusive first Company-local creation day; may be supplied without created_to.", "type": "string", "format": "date", "example": "2026-08-08" }, "created_to": { "description": "Inclusive last Company-local creation day; cannot precede created_from.", "type": "string", "format": "date", "example": "2026-08-08" }, "inactive_for_days": { "type": "integer", "minimum": 1 }, "sort_by": { "type": "string", "enum": [ "next_action_at", "last_activity_at", "created_at" ] }, "sort_order": { "description": "Requires sort_by. Defaults to asc for next_action_at and desc otherwise.", "type": "string", "enum": [ "asc", "desc" ] }, "search": { "description": "Grouped OR fragment across name, phone, and email. Measured in raw Unicode characters before trimming; whitespace-only values are invalid.", "type": "string", "maxLength": 255, "minLength": 1 }, "name": { "description": "Partial name fragment. Measured in raw Unicode characters before trimming; whitespace-only values are invalid.", "type": "string", "maxLength": 80, "minLength": 1 }, "phone": { "description": "Partial phone fragment; no telephone-format validation is applied. Measured in raw Unicode characters before trimming; whitespace-only values are invalid.", "type": "string", "maxLength": 30, "minLength": 1 }, "email": { "description": "Partial email fragment; no e-mail-format validation is applied. Measured in raw Unicode characters before trimming; whitespace-only values are invalid.", "type": "string", "maxLength": 255, "minLength": 1 } }, "type": "object", "additionalProperties": false }, "PotentialCustomerSearchItem": { "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "phone": { "type": "string" }, "phone_kind": { "type": "string" }, "email": { "type": "string" }, "email_kind": { "type": "string" }, "source": { "type": "string" }, "status": { "type": "string", "enum": [ "pre_qualified", "contacting", "discovery", "qualified", "proposal", "converted", "lost", "nurture" ] }, "status_changed_at": { "type": "string", "format": "date-time" }, "lost_reason": { "type": "string", "nullable": true, "maxLength": 255 }, "next_action_note": { "type": "string", "nullable": true, "maxLength": 400 }, "next_action_at": { "type": "string", "format": "date-time", "nullable": true }, "assigned_salesperson_id": { "type": "integer", "nullable": true }, "assigned_salesperson_name": { "type": "string", "nullable": true }, "labels": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "tone": { "type": "string" }, "archived": { "type": "boolean" } }, "type": "object" } }, "creator_id": { "type": "integer" }, "converted_client_id": { "type": "string", "format": "uuid", "nullable": true }, "notes": { "type": "string", "nullable": true }, "last_activity_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "company_id": { "type": "string" } }, "type": "object" }, "PotentialCustomersSearchMeta": { "properties": { "total": { "description": "Total rows matching the current filters.", "type": "integer" }, "per_page": { "type": "integer" }, "counts": { "description": "Filtered facets. Stage buckets exclude only status; without_next_action excludes only urgency. All retain view and other filters.", "type": "object", "additionalProperties": { "type": "integer" } }, "label_counts": { "description": "Counts excluding only selected labels; retains status, view and all other criteria.", "type": "object", "additionalProperties": { "type": "integer" } }, "current_page": { "type": "integer" } }, "type": "object" }, "PotentialCustomersSearchCounts": { "description": "Global tenant-wide queue counts; these are not narrowed by the current filters.", "properties": { "pre_qualified": { "type": "integer" }, "contacting": { "type": "integer" }, "discovery": { "type": "integer" }, "qualified": { "type": "integer" }, "proposal": { "type": "integer" }, "converted": { "type": "integer" }, "lost": { "type": "integer" }, "nurture": { "type": "integer" }, "total": { "description": "Global tenant-wide lead total across status buckets.", "type": "integer" }, "without_next_action": { "description": "Global tenant count; overlaps the status buckets and is not added to total.", "type": "integer" } }, "type": "object" }, "PotentialCustomersSearchResponse": { "description": "Identical for the GET list and the POST sensitive search.", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PotentialCustomerSearchItem" } }, "meta": { "$ref": "#/components/schemas/PotentialCustomersSearchMeta" }, "counts": { "deprecated": true, "allOf": [ { "$ref": "#/components/schemas/PotentialCustomersSearchCounts" } ] } }, "type": "object" }, "PotentialCustomersSearchValidationProblem": { "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string", "enum": [ "Unprocessable Entity" ] }, "status": { "type": "integer", "enum": [ 422 ] }, "detail": { "type": "string", "enum": [ "The given data was invalid." ] }, "error_code": { "type": "string", "nullable": true }, "errors": { "description": "Keys are drawn only from the canonical supported request fields below plus the fixed `_body` envelope key. A field validated per item also reports the failing index as `.` — for example `assigned_salesperson_id.0` — so the key space is the documented names plus their zero-based indexed variants, which is why additional properties are permitted rather than forbidden. The closed part is the set of *names*: unsupported property names — including forged tenant aliases such as companyId or company_id — collapse into `_body` and are never echoed, listed, or counted, because the name itself is attacker-controlled and may carry PII. Rejected values are never repeated in a message.", "properties": { "_body": { "type": "array", "items": { "type": "string", "enum": [ "The JSON body contains unsupported properties.", "The request body must be a JSON object." ] }, "minItems": 1 }, "page": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "per_page": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "status": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "source": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "assigned_salesperson_id": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "urgency": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "created_from": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "created_to": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "inactive_for_days": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "sort_by": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "sort_order": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "search": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "name": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "phone": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "email": { "type": "array", "items": { "type": "string" }, "minItems": 1 } }, "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" }, "minItems": 1 } } }, "type": "object" }, "PotentialCustomersSearchFailureProblem": { "description": "The store failed. No SQL text, binding, name, phone, email, search fragment, filesystem path, or driver message is returned in any environment.", "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string", "enum": [ "Internal Server Error" ] }, "status": { "type": "integer", "enum": [ 500 ] }, "detail": { "type": "string", "enum": [ "La búsqueda de clientes potenciales falló." ] }, "error_code": { "type": "string", "enum": [ "potential_customer_search_failed" ] }, "errors": { "type": "object", "nullable": true } }, "type": "object" }, "PriceListCreateRequest": { "required": [ "id", "code", "name", "currency" ], "properties": { "id": { "description": "Client-supplied list id.", "type": "string", "format": "uuid" }, "code": { "description": "Trimmed and uppercased; then 2 to 20 letters, digits, hyphens or underscores, starting and ending with a letter or a digit (price_list_code_invalid), unique per company (price_list_code_already_exists).", "type": "string", "example": "mayor", "maxLength": 255 }, "name": { "description": "1 to 100 characters once trimmed (price_list_name_invalid).", "type": "string", "example": "Precios al mayor", "maxLength": 255 }, "currency": { "description": "USD or VES, case-insensitive (price_list_currency_not_supported); it never changes afterwards.", "type": "string", "example": "USD", "maxLength": 8 }, "valid_from": { "description": "First day the list prices, included; absent or null leaves it open.", "type": "string", "format": "date", "nullable": true }, "valid_to": { "description": "Last day the list prices, included; not before valid_from (price_list_valid_to_before_valid_from).", "type": "string", "format": "date", "nullable": true } }, "type": "object" }, "PriceListUpdateRequest": { "description": "A full replacement: an omitted validity end is cleared.", "required": [ "code", "name", "currency" ], "properties": { "code": { "type": "string", "example": "MAYOR", "maxLength": 255 }, "name": { "type": "string", "example": "Precios al mayor", "maxLength": 255 }, "currency": { "description": "Must be the list's own currency (price_list_currency_cannot_change).", "type": "string", "example": "USD", "maxLength": 8 }, "valid_from": { "type": "string", "format": "date", "nullable": true }, "valid_to": { "type": "string", "format": "date", "nullable": true } }, "type": "object" }, "PriceListWriteResponse": { "required": [ "id", "code", "name", "currency", "valid_from", "valid_to", "status" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string", "example": "MAYOR" }, "name": { "type": "string", "example": "Precios al mayor" }, "currency": { "type": "string", "enum": [ "USD", "VES" ] }, "valid_from": { "type": "string", "format": "date", "nullable": true }, "valid_to": { "type": "string", "format": "date", "nullable": true }, "status": { "type": "string", "enum": [ "active", "inactive" ] } }, "type": "object" }, "PriceList": { "required": [ "id", "code", "name", "currency", "valid_from", "valid_to", "status", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string", "example": "MAYOR" }, "name": { "type": "string", "example": "Precios al mayor" }, "currency": { "type": "string", "enum": [ "USD", "VES" ] }, "valid_from": { "type": "string", "format": "date", "nullable": true }, "valid_to": { "type": "string", "format": "date", "nullable": true }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "created_at": { "type": "string", "format": "date-time", "nullable": true }, "updated_at": { "type": "string", "format": "date-time", "nullable": true } }, "type": "object" }, "PriceListList": { "required": [ "data", "current_page", "last_page", "per_page", "total", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PriceList" } }, "current_page": { "type": "integer" }, "last_page": { "description": "1 when the list is empty.", "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "meta": { "required": [ "counts" ], "properties": { "counts": { "description": "Lists per status under the same filters but the status one.", "required": [ "active", "inactive" ], "properties": { "active": { "type": "integer" }, "inactive": { "type": "integer" } }, "type": "object" } }, "type": "object" } }, "type": "object" }, "PriceListMoney": { "required": [ "amount", "currency" ], "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "example": "8.00" }, "currency": { "type": "string", "enum": [ "USD", "VES" ] } }, "type": "object" }, "PriceListEntryCreateRequest": { "required": [ "id", "item_id", "min_quantity", "unit_price" ], "properties": { "id": { "description": "Client-supplied price id.", "type": "string", "format": "uuid" }, "item_id": { "description": "An active item of the company's catalog (price_list_entry_item_not_found, price_list_entry_item_inactive); it never changes afterwards.", "type": "string", "format": "uuid" }, "min_quantity": { "description": "Base units from which the price applies: at least 1, up to 11 integer and 4 decimal digits (price_list_entry_min_quantity_invalid); unique per list and item (price_list_entry_already_exists). A minimum of exactly 1 also applies to a fraction of a base unit; any other minimum, 1.5 included, applies only from that many base units (ADR 0374).", "type": "string", "example": "12", "maxLength": 32 }, "unit_price": { "required": [ "amount", "currency" ], "properties": { "amount": { "description": "Never negative, up to 13 integer and 2 decimal digits (price_list_entry_unit_price_invalid).", "type": "string", "example": "8.00", "maxLength": 32 }, "currency": { "description": "The list's currency (price_list_entry_currency_mismatch).", "type": "string", "example": "USD", "maxLength": 8 } }, "type": "object" } }, "type": "object" }, "PriceListEntryUpdateRequest": { "description": "The item of a price never changes: to price another item, remove the price and add a new one.", "required": [ "min_quantity", "unit_price" ], "properties": { "min_quantity": { "type": "string", "example": "24", "maxLength": 32 }, "unit_price": { "required": [ "amount", "currency" ], "properties": { "amount": { "type": "string", "example": "7.50", "maxLength": 32 }, "currency": { "type": "string", "example": "USD", "maxLength": 8 } }, "type": "object" } }, "type": "object" }, "PriceListEntryWriteResponse": { "required": [ "id", "price_list_id", "item_id", "min_quantity", "unit_price" ], "properties": { "id": { "type": "string", "format": "uuid" }, "price_list_id": { "type": "string", "format": "uuid" }, "item_id": { "type": "string", "format": "uuid" }, "min_quantity": { "type": "string", "pattern": "^\\d+\\.\\d{4}$", "example": "12.0000" }, "unit_price": { "$ref": "#/components/schemas/PriceListMoney" } }, "type": "object" }, "PriceListEntryRow": { "required": [ "id", "price_list_id", "item_id", "item_code", "item_name", "item_barcode", "item_sku", "item_status", "min_quantity", "unit_price", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "price_list_id": { "type": "string", "format": "uuid" }, "item_id": { "type": "string", "format": "uuid" }, "item_code": { "type": "string", "example": "ART-0001" }, "item_name": { "type": "string", "example": "Arroz 1 kg" }, "item_barcode": { "type": "string", "nullable": true }, "item_sku": { "type": "string", "nullable": true }, "item_status": { "description": "As the catalog has it now: a price stays editable after its item is inactivated.", "type": "string", "enum": [ "active", "inactive" ] }, "min_quantity": { "type": "string", "pattern": "^\\d+\\.\\d{4}$", "example": "12.0000" }, "unit_price": { "$ref": "#/components/schemas/PriceListMoney" }, "created_at": { "type": "string", "format": "date-time", "nullable": true }, "updated_at": { "type": "string", "format": "date-time", "nullable": true } }, "type": "object" }, "PriceListEntryList": { "required": [ "data", "current_page", "last_page", "per_page", "total" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PriceListEntryRow" } }, "current_page": { "type": "integer" }, "last_page": { "description": "1 when the list has no prices.", "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" } }, "type": "object" }, "PriceListProblem": { "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "error_code": { "type": "string", "nullable": true }, "errors": { "description": "Request validation messages by field.", "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "field_errors": { "description": "A domain refusal's messages by request field, such as code or unit_price.amount.", "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "price_list_currency": { "description": "With price_list_currency_cannot_change or price_list_entry_currency_mismatch: the list's currency.", "type": "string", "enum": [ "USD", "VES" ] }, "price_list_status": { "description": "With price_list_status_transition_not_allowed: the status the list already has.", "type": "string", "enum": [ "active", "inactive" ] }, "sales_channels": { "description": "With price_list_in_use_by_sales_channels: the channels that name the list as their default, at most 10, by code.", "type": "array", "items": { "required": [ "id", "code", "name" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string", "example": "QA-VITRINA" }, "name": { "type": "string", "example": "Vitrina QA" } }, "type": "object" } }, "sales_channels_total": { "description": "With price_list_in_use_by_sales_channels: how many channels name the list, shown or not.", "type": "integer", "minimum": 1 } }, "type": "object" }, "PriceListRefusal422": { "description": "A request validation failure (error_code null, errors by field) or a domain refusal (its error_code, errors null, field_errors by field).", "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string" }, "error_code": { "type": "string", "example": "price_list_entry_unit_price_invalid", "nullable": true }, "errors": { "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "field_errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "price_list_currency": { "type": "string", "enum": [ "USD", "VES" ] } }, "type": "object" }, "PriceListImportAccepted": { "description": "The upload was taken and imported (MER-3884); read its status by this id.", "required": [ "import_id" ], "properties": { "import_id": { "type": "string", "format": "uuid" } }, "type": "object" }, "PriceListImportStatus": { "description": "A price import (MER-3884). completed: at least one row was created, updated or unchanged, and errors may still list rejected rows. failed: no row was imported and errors lists every rejected row; or the file was refused whole, with one reason and every count at 0; or an unexpected failure interrupted it, keeping the counts and row reasons of the rows judged before it (those rows stay saved) followed by the interruption's reason as the last message, which before any row reads like a whole-file failure.", "required": [ "id", "price_list_id", "status", "original_filename", "created_count", "updated_count", "unchanged_count", "error_count", "total_count", "errors", "requested_at", "started_at", "completed_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "price_list_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed" ] }, "original_filename": { "type": "string", "example": "precios-mayo.xlsx" }, "created_count": { "description": "Prices the import created.", "type": "integer", "minimum": 0 }, "updated_count": { "description": "Prices whose amount the import changed.", "type": "integer", "minimum": 0 }, "unchanged_count": { "description": "Rows whose price the list already held, «sin cambios».", "type": "integer", "minimum": 0 }, "error_count": { "description": "Rejected rows; each has exactly one message in errors.", "type": "integer", "minimum": 0 }, "total_count": { "description": "created + updated + unchanged + error; blank rows are not counted.", "type": "integer", "minimum": 0 }, "errors": { "description": "Spanish reasons, «Fila N - Código 'X': motivo», in file order; or one whole-file reason; an interrupted import appends its reason last, so it holds error_count + 1 messages.", "type": "array", "items": { "type": "string", "example": "Fila 3 - Código 'ITM202699999': no existe un artículo con ese código en la empresa." } }, "requested_at": { "type": "string", "format": "date-time", "nullable": true }, "started_at": { "type": "string", "format": "date-time", "nullable": true }, "completed_at": { "type": "string", "format": "date-time", "nullable": true } }, "type": "object" }, "PriceListMiddlewareNotFound": { "description": "Answered before the controller runs: by the tenancy middleware for an unknown company, or by the API key guardrails for a key bound to another company.", "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Recurso no encontrado" } }, "type": "object" }, "PriceListNotFound404": { "oneOf": [ { "$ref": "#/components/schemas/PriceListProblem" }, { "$ref": "#/components/schemas/PriceListMiddlewareNotFound" } ] }, "SalePriceOverrideLine": { "required": [ "index", "item_id", "unit_id", "proposed_price", "unit_price" ], "properties": { "index": { "description": "The 0-based position of the line in the request's items (items.N); the same item may appear on several lines.", "type": "integer", "example": 0, "minimum": 0 }, "item_id": { "description": "As the request sent it.", "type": "string", "format": "uuid" }, "unit_id": { "description": "As the request sent it.", "type": "string", "format": "uuid" }, "proposed_price": { "description": "The price the server proposes per one unit of the line's unit: the list tier or the Precio base times the unit factor, converted to the document currency at the rate of the emission date when the currencies differ, rounded once. Sales orders and invoices carry no list, so theirs is always the Precio base.", "type": "string", "pattern": "^\\d+\\.\\d{2}$", "example": "365.00" }, "unit_price": { "description": "The price the request sent, at two decimals.", "type": "string", "pattern": "^\\d+\\.\\d{2}$", "example": "360.00" } }, "type": "object", "additionalProperties": false }, "SalePriceOverrideNotAllowed": { "description": "A line changed the price the server proposes for it and the user lacks backoffice.sales.price-lists.override. Only priced lines whose price differs appear, in request order. On a sales order or invoice update, a line that keeps its stored item, unit and price in the same currency never does; on a sales quote update, a line that keeps its stored item, unit, quantity and price while the quote keeps its price list and currency never does. Nothing is saved.", "required": [ "title", "status", "detail", "error_code", "errors", "currency", "lines" ], "properties": { "title": { "type": "string", "example": "Forbidden" }, "status": { "type": "integer", "example": 403 }, "detail": { "type": "string", "example": "El precio de venta propuesto de 1 línea(s) se cambió sin el permiso backoffice.sales.price-lists.override." }, "error_code": { "type": "string", "enum": [ "sale_price_override_not_allowed" ] }, "errors": { "description": "Always null for this refusal.", "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "currency": { "description": "The document currency of every amount in lines.", "type": "string", "enum": [ "USD", "VES" ] }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/SalePriceOverrideLine" }, "minItems": 1 } }, "type": "object", "additionalProperties": false }, "SalesDocumentForbidden": { "description": "The user lacks the endpoint's own permission.", "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string", "example": "Unauthorized" }, "status": { "type": "integer", "example": 403 }, "detail": { "type": "string", "example": "You do not have permission to access this resource." }, "error_code": { "description": "Always null: a body with an error_code is never this answer.", "type": "string", "nullable": true, "enum": [ null ] }, "errors": { "description": "Always null.", "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object", "additionalProperties": false }, "SalePriceListSelectionNotAllowed": { "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string", "enum": [ "Forbidden" ] }, "status": { "type": "integer", "enum": [ 403 ] }, "detail": { "type": "string" }, "error_code": { "type": "string", "enum": [ "sale_price_list_selection_not_allowed" ] }, "errors": { "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object", "additionalProperties": false }, "SalesDocumentWrite403": { "oneOf": [ { "$ref": "#/components/schemas/SalePriceMiddlewareForbidden" }, { "$ref": "#/components/schemas/SalesDocumentForbidden" }, { "$ref": "#/components/schemas/SalePriceOverrideNotAllowed" }, { "$ref": "#/components/schemas/SalePriceListSelectionNotAllowed" } ] }, "SalePriceResolveRequest": { "required": [ "date", "currency", "lines" ], "properties": { "price_list_id": { "description": "The list to price from; absent or null resolves the items' Precio base. A list also needs backoffice.sales.price-lists.view (403 otherwise, whether it exists or not); unknown or another company's: price_list_not_found.", "type": "string", "format": "uuid", "nullable": true }, "channel_id": { "description": "The Canal whose default list prices the lines, instead of price_list_id: sending both is refused with 422 on channel_id, though a null price_list_id beside it counts as absent. It needs the same permissions as a list (403 otherwise, whether it exists or not); unknown or another company's: sales_channel_not_found. A channel without a default list resolves the Precio base, and an inactive channel still resolves.", "type": "string", "format": "uuid", "nullable": true }, "date": { "description": "The company day the lines are priced on, exactly Y-m-d: it picks whether the list applies and the rate (the first value date on or after it, ADR 0143).", "type": "string", "format": "date", "example": "2026-10-14" }, "currency": { "description": "The currency of `price`, exactly USD or VES.", "type": "string", "enum": [ "USD", "VES" ] }, "lines": { "description": "Up to 200 lines, priced in order; resolve larger documents in batches.", "type": "array", "items": { "$ref": "#/components/schemas/SalePriceResolveRequestLine" }, "maxItems": 200, "minItems": 1 } }, "type": "object" }, "SalePriceResolveRequestLine": { "required": [ "item_id", "unit_id", "quantity" ], "properties": { "item_id": { "type": "string", "format": "uuid" }, "unit_id": { "description": "One of the item's units (sale_price_line_unit_not_of_item otherwise, on lines.N.unit_id).", "type": "string", "format": "uuid" }, "quantity": { "description": "Positive, up to 11 integer and 4 decimal digits, as a string, in the line's unit: its base quantity picks the list tier.", "type": "string", "pattern": "^(?:[1-9]\\d{0,10}(?:\\.\\d{1,4})?|0\\.(?=\\d*[1-9])\\d{1,4})$", "example": "12" } }, "type": "object", "additionalProperties": false }, "SalePriceMoney": { "required": [ "amount", "currency" ], "properties": { "amount": { "description": "Exact; parse it as a decimal string, never as a JSON number.", "type": "string", "pattern": "^\\d+\\.\\d{2}$", "example": "365.00" }, "currency": { "type": "string", "enum": [ "USD", "VES" ] } }, "type": "object", "nullable": true }, "SalePriceRate": { "description": "The published VES-per-USD rate the price converted with, and the value date it was selected for.", "required": [ "value_date", "rate" ], "properties": { "value_date": { "type": "string", "format": "date", "example": "2026-10-14" }, "rate": { "type": "string", "pattern": "^\\d+\\.\\d{8}$", "example": "36.50000000" } }, "type": "object", "nullable": true }, "SalePriceResolvedLine": { "description": "priced: price and fingerprint set; rate set only when converted, and then price comes from the unrounded line-unit price, never from source_price. unpriced: neither a list price nor a Precio base; everything else null. rate_unavailable: source and source_price kept, price, rate and fingerprint null. rounds_to_zero: a list price or Precio base above 0.00 whose price for one line unit rounds to 0.00 in the requested currency (ADR 0381); source and source_price kept, price, rate and fingerprint null, so the line takes no proposed price and never falls back to source_price.", "required": [ "item_id", "unit_id", "quantity", "status", "source", "source_price", "price", "rate", "fingerprint" ], "properties": { "item_id": { "type": "string", "format": "uuid" }, "unit_id": { "type": "string", "format": "uuid" }, "quantity": { "type": "string", "pattern": "^\\d+\\.\\d{4}$", "example": "12.0000" }, "status": { "type": "string", "enum": [ "priced", "unpriced", "rate_unavailable", "rounds_to_zero" ] }, "source": { "type": "string", "nullable": true, "enum": [ "price_list", "base_price", null ] }, "source_price": { "$ref": "#/components/schemas/SalePriceMoney" }, "price": { "$ref": "#/components/schemas/SalePriceMoney" }, "rate": { "$ref": "#/components/schemas/SalePriceRate" }, "fingerprint": { "description": "The «Huella de precio»: send it back to confirm the price; a stale one is refused with quote_changed.", "type": "string", "pattern": "^[a-f0-9]{64}$", "nullable": true } }, "type": "object" }, "SalePriceResolution": { "required": [ "date", "currency", "price_list_id", "channel_id", "lines" ], "properties": { "date": { "type": "string", "format": "date" }, "currency": { "type": "string", "enum": [ "USD", "VES" ] }, "price_list_id": { "description": "The list the resolution chose: the one sent, or the channel's default list; null when neither names one. It is echoed even when the list does not apply on the day and the lines fall back to the Precio base.", "type": "string", "format": "uuid", "nullable": true }, "channel_id": { "description": "The channel sent, whose default list the resolution chose; null when none was sent.", "type": "string", "format": "uuid", "nullable": true }, "lines": { "description": "In request order.", "type": "array", "items": { "$ref": "#/components/schemas/SalePriceResolvedLine" } } }, "type": "object" }, "SalePriceResolutionRefusal422": { "description": "A request validation failure (error_code null, errors by field) or a domain refusal (its error_code, errors null; field_errors by field for sale_price_line_unit_not_of_item).", "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string" }, "error_code": { "type": "string", "example": "sale_price_line_unit_not_of_item", "nullable": true }, "errors": { "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "field_errors": { "description": "By line field, such as lines.1.unit_id.", "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" }, "SalePriceMiddlewareForbidden": { "description": "Answered before the controller runs, by the company access or tenant membership middleware, for a caller who does not belong to the company.", "required": [ "title", "status", "detail" ], "properties": { "title": { "type": "string", "example": "Forbidden" }, "status": { "type": "integer", "example": 403 }, "detail": { "type": "string", "example": "You do not have access to this tenant" }, "reason": { "description": "Only from the tenant membership middleware.", "type": "string" } }, "type": "object", "additionalProperties": false }, "SalePriceResolution403": { "oneOf": [ { "$ref": "#/components/schemas/PriceListProblem" }, { "$ref": "#/components/schemas/SalePriceMiddlewareForbidden" } ] }, "ClientStatementAmount": { "type": "string", "pattern": "^-?[0-9]+[.][0-9]{2}$", "example": "50.00" }, "ClientStatementMessageError": { "required": [ "message" ], "properties": { "message": { "type": "string" } }, "type": "object" }, "ClientStatementValidationError": { "required": [ "message", "errors" ], "properties": { "message": { "type": "string" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" }, "ClientStatementForbiddenError": { "required": [ "title", "status", "detail" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "reason": { "type": "string" } }, "type": "object" }, "ClientStatementProblem": { "required": [ "title", "status", "detail", "error_code" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "error_code": { "type": "string", "nullable": true }, "errors": { "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" }, "ClientStatementClient": { "required": [ "id", "code", "name" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "ClientStatementRange": { "required": [ "from", "to" ], "properties": { "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" } }, "type": "object" }, "ClientStatementLine": { "description": "One movement of the client's debt inside the range with the running balance it leaves. Exactly one of debit and credit is above zero.", "required": [ "date", "type", "document_id", "document_code", "reference", "origin_document_code", "debit", "credit", "balance", "has_approximate_date" ], "properties": { "date": { "description": "The day the movement falls on in the company calendar", "type": "string", "format": "date" }, "type": { "description": "Approved invoices, opening invoices and debit notes raise the debt at their emission date and approved credit notes lower it by their whole total; collections lower it on their applied date; an advance application lowers it by what it relieved on the invoice, in the invoice's currency, on its application date, and its reversal raises it back on the day of its ledger reversal entry; a received withholding lowers it by what it relieved on the invoice, in the invoice's currency, on the day it was received, whether reported or supported, and its voiding raises it back on the day it was voided; the client's adjustment of a received withholding (MER-3697) raises it again by what it restored on the invoice, in the invoice's currency, on the day the adjustment was received, named by its own certificate, and the adjustment's voiding lowers it back on the day it was voided; a credit balance refund (MER-3631) raises it by the Customer Credit it paid out of each credit note, in the note's currency, on the refund's date, and its cancellation lowers it back on the day the refund was cancelled, while paying out an advance moves nothing; each cancellation reverses its original on the day it was cancelled. Credit-note applications are never movements: a credit note counts once; advance applications are. Within a day, lines follow this order, then document code", "type": "string", "enum": [ "opening_invoice", "invoice", "debit_note", "credit_note", "received_withholding", "received_withholding_adjustment", "collection", "advance_application", "credit_balance_refund", "received_withholding_adjustment_voided", "received_withholding_voided", "collection_cancellation", "advance_application_reversal", "credit_balance_refund_cancellation", "credit_note_cancellation", "debit_note_cancellation", "invoice_cancellation" ] }, "document_id": { "description": "The sales document or collection the line comes from or, for an advance application or its reversal, the advance (a collection of kind advance); for a received withholding or its voiding, the received withholding; for a credit balance refund or its cancellation, the refund (a collection of kind refund)", "type": "string", "format": "uuid" }, "document_code": { "description": "Internal code of the sales document or collection or, for an advance application or its reversal, of the advance (a collection of kind advance); for a received withholding or its voiding, its certificate number, or the code of the invoice it relieved while it is reported; for a credit balance refund or its cancellation, of the refund (a collection of kind refund)", "type": "string" }, "reference": { "description": "The fiscal invoice number of a sales document, or the collection's reference, the advance's for an advance application or its reversal; for a received withholding or its voiding, its certificate number, null while it is reported; for a credit balance refund or its cancellation, the refund's (a collection of kind refund)", "type": "string", "nullable": true }, "origin_document_code": { "description": "Internal code of the invoice a debit or credit note was issued on, of the invoice an advance application relieved or its reversal restored, of the invoice a received withholding relieved or its voiding restored, or of the credit note a credit balance refund paid out, on the refund and on its cancellation; null otherwise", "type": "string", "nullable": true }, "debit": { "description": "What the line adds to the debt, 0.00 when it lowers it", "type": "string", "pattern": "^[0-9]+[.][0-9]{2}$" }, "credit": { "description": "What the line takes off the debt, 0.00 when it raises it", "type": "string", "pattern": "^[0-9]+[.][0-9]{2}$" }, "balance": { "description": "Running balance after the line; negative when credit exceeds debt", "allOf": [ { "$ref": "#/components/schemas/ClientStatementAmount" } ] }, "has_approximate_date": { "description": "A cancellation is dated on its stored cancelled_on day; without one, on the company day of its recorded instant (last update), and then this is true. An advance application's reversal is dated on its ledger reversal entry; without one, on the company day of its reverted instant, and then this is true. A received withholding's voiding is dated on the day it was voided; without one, on the company day of its voided instant, and then this is true. A credit balance refund's cancellation is dated on the refund's cancelled_on day; without one, on the company day of its reverted instant, and then this is true", "type": "boolean" } }, "type": "object" }, "ClientStatementTotals": { "required": [ "debits", "credits" ], "properties": { "debits": { "type": "string", "pattern": "^[0-9]+[.][0-9]{2}$" }, "credits": { "type": "string", "pattern": "^[0-9]+[.][0-9]{2}$" } }, "type": "object" }, "ClientStatementSection": { "description": "The client's debt in one document currency: closing_balance = opening_balance + totals.debits - totals.credits. Currencies are never summed.", "required": [ "currency", "opening_balance", "lines", "totals", "closing_balance" ], "properties": { "currency": { "type": "string", "enum": [ "USD", "VES", "USDT", "EUR", "DOP" ] }, "opening_balance": { "description": "Every movement dated before from", "allOf": [ { "$ref": "#/components/schemas/ClientStatementAmount" } ] }, "lines": { "description": "Ordered by date, movement type and document code", "type": "array", "items": { "$ref": "#/components/schemas/ClientStatementLine" } }, "totals": { "$ref": "#/components/schemas/ClientStatementTotals" }, "closing_balance": { "description": "As of a to on or after the latest movement it equals the client's receivables aging total in this currency, unless a document is dated after today", "allOf": [ { "$ref": "#/components/schemas/ClientStatementAmount" } ] } }, "type": "object" }, "ClientStatementOpenCredit": { "required": [ "type", "currency", "document_id", "document_code", "date", "amount" ], "properties": { "type": { "description": "customer_credit: the Customer Credit a credit note still holds, already included in the section balances; advance: what an open customer advance still holds, not included in them, since an advance moves no debt until it is applied", "type": "string", "enum": [ "customer_credit", "advance" ] }, "currency": { "type": "string", "enum": [ "USD", "VES", "USDT", "EUR", "DOP" ] }, "document_id": { "description": "The credit note or the advance collection", "type": "string", "format": "uuid" }, "document_code": { "type": "string" }, "date": { "description": "The credit note's emission date, or the day the advance was collected", "type": "string", "format": "date" }, "amount": { "type": "string", "pattern": "^[0-9]+[.][0-9]{2}$" } }, "type": "object" }, "ClientStatement": { "description": "Informational Account Statement of one client over a range, one section per document currency ordered by currency code, never a fiscal document.", "required": [ "client", "range", "currency", "as_of", "has_approximate_dates", "sections", "open_credits" ], "properties": { "client": { "$ref": "#/components/schemas/ClientStatementClient" }, "range": { "$ref": "#/components/schemas/ClientStatementRange" }, "currency": { "description": "The requested currency, null when every currency is stated", "type": "string", "nullable": true, "enum": [ "USD", "VES", "USDT", "EUR", "DOP" ] }, "as_of": { "description": "Today in the company timezone; it dates open_credits only", "type": "string", "format": "date" }, "has_approximate_dates": { "description": "Some line, or some movement folded into an opening balance, has an approximate date", "type": "boolean" }, "sections": { "type": "array", "items": { "$ref": "#/components/schemas/ClientStatementSection" } }, "open_credits": { "description": "Customer Credit and open advances the client holds as of as_of, by currency, then date, then document code. Customer Credit is already included in the section balances; advances are not.", "type": "array", "items": { "$ref": "#/components/schemas/ClientStatementOpenCredit" } } }, "type": "object" }, "ReceivablesAgingAmount": { "type": "string", "pattern": "^-?[0-9]+[.][0-9]{2}$", "example": "300.00" }, "ReceivablesAgingMessageError": { "required": [ "message" ], "properties": { "message": { "type": "string" } }, "type": "object" }, "ReceivablesAgingValidationError": { "required": [ "message", "errors" ], "properties": { "message": { "type": "string" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" }, "ReceivablesAgingForbiddenError": { "required": [ "title", "status", "detail" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "reason": { "type": "string" } }, "type": "object" }, "ReceivablesAgingProblem": { "required": [ "title", "status", "detail", "error_code" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "error_code": { "type": "string", "nullable": true }, "errors": { "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" }, "ReceivablesAgingRow": { "description": "One client's open receivables in one document currency. Buckets, credit and total are in that currency; total = current + d1_30 + d31_60 + d61_90 + over_90 + credit.", "required": [ "counterparty_id", "counterparty_code", "counterparty_name", "currency", "current", "d1_30", "d31_60", "d61_90", "over_90", "credit", "total", "reporting_total", "functional_total", "has_approximate_due_dates" ], "properties": { "counterparty_id": { "type": "string", "format": "uuid" }, "counterparty_code": { "description": "Null only when the client row is missing, an integrity anomaly; the name is then empty", "type": "string", "nullable": true }, "counterparty_name": { "type": "string" }, "currency": { "type": "string", "enum": [ "USD", "VES", "USDT", "EUR", "DOP" ] }, "current": { "$ref": "#/components/schemas/ReceivablesAgingAmount" }, "d1_30": { "$ref": "#/components/schemas/ReceivablesAgingAmount" }, "d31_60": { "$ref": "#/components/schemas/ReceivablesAgingAmount" }, "d61_90": { "$ref": "#/components/schemas/ReceivablesAgingAmount" }, "over_90": { "$ref": "#/components/schemas/ReceivablesAgingAmount" }, "credit": { "description": "Customer Credit still held, zero or negative", "allOf": [ { "$ref": "#/components/schemas/ReceivablesAgingAmount" } ] }, "total": { "$ref": "#/components/schemas/ReceivablesAgingAmount" }, "reporting_total": { "description": "Stored reporting-book balances, Customer Credit negative", "allOf": [ { "$ref": "#/components/schemas/ReceivablesAgingAmount" } ] }, "functional_total": { "description": "Stored functional-book balances, Customer Credit negative", "allOf": [ { "$ref": "#/components/schemas/ReceivablesAgingAmount" } ] }, "has_approximate_due_dates": { "description": "A debt was aged without its exact due date: an opening invoice without its Opening Document, or a stored payment term outside the known vocabulary, aged from its emission date", "type": "boolean" } }, "type": "object" }, "ReceivablesAgingCurrencyTotal": { "description": "Every row of one document currency added up; currencies are never summed together.", "required": [ "currency", "current", "d1_30", "d31_60", "d61_90", "over_90", "credit", "total", "reporting_total", "functional_total" ], "properties": { "currency": { "type": "string", "enum": [ "USD", "VES", "USDT", "EUR", "DOP" ] }, "current": { "$ref": "#/components/schemas/ReceivablesAgingAmount" }, "d1_30": { "$ref": "#/components/schemas/ReceivablesAgingAmount" }, "d31_60": { "$ref": "#/components/schemas/ReceivablesAgingAmount" }, "d61_90": { "$ref": "#/components/schemas/ReceivablesAgingAmount" }, "over_90": { "$ref": "#/components/schemas/ReceivablesAgingAmount" }, "credit": { "$ref": "#/components/schemas/ReceivablesAgingAmount" }, "total": { "$ref": "#/components/schemas/ReceivablesAgingAmount" }, "reporting_total": { "$ref": "#/components/schemas/ReceivablesAgingAmount" }, "functional_total": { "$ref": "#/components/schemas/ReceivablesAgingAmount" } }, "type": "object" }, "ReceivablesAging": { "description": "Open receivables as of today in the company timezone, one row per client and document currency. Unfiltered, functional_total and reporting_total equal the receivable control accounts' ledger balance in each book, except while an unrealized revaluation entry on a receivable account is open (ADR 0122). Any filter applies to debts and Customer Credit alike, so filtered totals do not equal the ledger.", "required": [ "as_of", "functional_currency", "reporting_currency", "has_approximate_due_dates", "rows", "totals_by_currency", "functional_total", "reporting_total" ], "properties": { "as_of": { "description": "Today in the company timezone", "type": "string", "format": "date" }, "functional_currency": { "type": "string", "enum": [ "USD", "VES", "USDT", "EUR", "DOP" ] }, "reporting_currency": { "type": "string", "enum": [ "USD", "VES", "USDT", "EUR", "DOP" ] }, "has_approximate_due_dates": { "type": "boolean" }, "rows": { "description": "Ordered by client name, client id and currency", "type": "array", "items": { "$ref": "#/components/schemas/ReceivablesAgingRow" } }, "totals_by_currency": { "description": "Ordered by currency code", "type": "array", "items": { "$ref": "#/components/schemas/ReceivablesAgingCurrencyTotal" } }, "functional_total": { "description": "Every row's functional_total, in the functional currency", "allOf": [ { "$ref": "#/components/schemas/ReceivablesAgingAmount" } ] }, "reporting_total": { "description": "Every row's reporting_total, in the reporting currency", "allOf": [ { "$ref": "#/components/schemas/ReceivablesAgingAmount" } ] } }, "type": "object" }, "StorefrontKeyView": { "required": [ "id", "label", "prefix", "issued_by", "issued_at", "last_used_at", "revoked_by", "revoked_at" ], "properties": { "id": { "description": "Clave de Vitrina API components (MER-4188).", "type": "string", "format": "uuid" }, "label": { "type": "string", "example": "Servidor producción", "maxLength": 60 }, "prefix": { "type": "string", "example": "mtsk_Ab12Cd", "maxLength": 12 }, "issued_by": { "type": "string" }, "issued_at": { "type": "string", "format": "date-time" }, "last_used_at": { "type": "string", "format": "date-time", "nullable": true }, "revoked_by": { "type": "string", "nullable": true }, "revoked_at": { "type": "string", "format": "date-time", "nullable": true } }, "type": "object" }, "StorefrontKeyIssueRequest": { "required": [ "id", "label" ], "properties": { "id": { "description": "Client-supplied key id.", "type": "string", "format": "uuid" }, "label": { "description": "1 to 60 characters once trimmed (storefront_key_label_invalid).", "type": "string", "example": "Servidor producción", "maxLength": 60 } }, "type": "object" }, "StorefrontKeyIssueResponse": { "required": [ "id", "label", "prefix", "issued_by", "issued_at", "last_used_at", "revoked_by", "revoked_at", "secret" ], "properties": { "id": { "type": "string", "format": "uuid" }, "label": { "type": "string" }, "prefix": { "type": "string", "maxLength": 12 }, "issued_by": { "type": "string" }, "issued_at": { "type": "string", "format": "date-time" }, "last_used_at": { "type": "string", "format": "date-time", "nullable": true }, "revoked_by": { "type": "string", "nullable": true }, "revoked_at": { "type": "string", "format": "date-time", "nullable": true }, "secret": { "description": "One-time plaintext Clave de Vitrina (mtsk_ + 43 base62); never returned again.", "type": "string", "example": "mtsk_0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabc" } }, "type": "object" }, "StorefrontKeysListResponse": { "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/StorefrontKeyView" } } }, "type": "object" }, "StorefrontKeyProblem": { "required": [ "title", "status", "detail", "error_code" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "error_code": { "type": "string", "nullable": true }, "errors": { "type": "object", "nullable": true } }, "type": "object" }, "SalesChannelCreateRequest": { "required": [ "id", "code", "name", "kind", "location_id", "origins" ], "properties": { "id": { "description": "Client-supplied channel id.", "type": "string", "format": "uuid" }, "code": { "description": "Trimmed and uppercased; then 2 to 20 letters, digits, hyphens or underscores (sales_channel_code_invalid), unique per company (sales_channel_code_already_exists). Fixed after create.", "type": "string", "example": "detal", "maxLength": 255 }, "name": { "description": "1 to 100 characters once trimmed (sales_channel_name_invalid).", "type": "string", "example": "Vitrina detal", "maxLength": 255 }, "kind": { "description": "Fixed after create (sales_channel_kind_invalid).", "type": "string", "enum": [ "pos", "storefront" ] }, "location_id": { "description": "Active inventoried location of the company.", "type": "string", "format": "uuid" }, "default_price_list_id": { "description": "Optional active price list; null means Precio base.", "type": "string", "format": "uuid", "nullable": true }, "origins": { "description": "0 to 10 exact origins; empty for pos (origins_not_allowed_for_pos).", "type": "array", "items": { "type": "string" } }, "low_stock_threshold": { "description": "Optional umbral de escasez 1–999 for storefront only (MER-4192); null/absent means no threshold; pos refuses non-null (low_stock_threshold_not_allowed_for_pos).", "type": "integer", "example": 2, "nullable": true, "maximum": 999, "minimum": 1 } }, "type": "object" }, "SalesChannelUpdateRequest": { "description": "Code and kind are not accepted on update.", "required": [ "name", "location_id", "origins" ], "properties": { "name": { "type": "string", "example": "Vitrina detal", "maxLength": 255 }, "location_id": { "type": "string", "format": "uuid" }, "default_price_list_id": { "type": "string", "format": "uuid", "nullable": true }, "origins": { "type": "array", "items": { "type": "string" } }, "low_stock_threshold": { "description": "Optional; omit keeps the stored umbral; null clears it.", "type": "integer", "nullable": true, "maximum": 999, "minimum": 1 }, "revalidation_url": { "description": "Storefront only. Omit keeps; null clears. https://host[:port]/path; http://localhost or http://127.0.0.1 only in development; no user, password or fragment (revalidation_url_invalid); pos refuses non-null (revalidation_not_allowed_for_pos).", "type": "string", "example": "https://tienda.example.com/api/revalidate", "nullable": true, "maxLength": 255 } }, "type": "object" }, "SalesChannelWriteResponse": { "required": [ "id", "code", "name", "kind", "location_id", "default_price_list_id", "origins", "low_stock_threshold", "revalidation_url", "has_revalidation_secret", "revalidation_secret_rotated_at", "status" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string", "example": "DETAL" }, "name": { "type": "string", "example": "Vitrina detal" }, "kind": { "type": "string", "enum": [ "pos", "storefront" ] }, "location_id": { "type": "string", "format": "uuid" }, "default_price_list_id": { "type": "string", "format": "uuid", "nullable": true }, "origins": { "type": "array", "items": { "type": "string" } }, "low_stock_threshold": { "type": "integer", "nullable": true }, "revalidation_url": { "description": "URL de revalidación the backend notifies (MER-4193); storefront only.", "type": "string", "example": "https://tienda.example.com/api/revalidate", "nullable": true, "maxLength": 255 }, "has_revalidation_secret": { "description": "Whether a Secreto de revalidación exists. The secret itself is returned only once, when generated.", "type": "boolean" }, "revalidation_secret_rotated_at": { "description": "When the Secreto de revalidación was last generated (ISO 8601); null without a secret.", "type": "string", "format": "date-time", "example": "2026-10-29T14:00:00+00:00", "nullable": true }, "status": { "type": "string", "enum": [ "active", "inactive" ] } }, "type": "object" }, "SalesChannel": { "required": [ "id", "code", "name", "kind", "location_id", "default_price_list_id", "origins", "low_stock_threshold", "revalidation_url", "has_revalidation_secret", "revalidation_secret_rotated_at", "status", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string", "example": "DETAL" }, "name": { "type": "string", "example": "Vitrina detal" }, "kind": { "type": "string", "enum": [ "pos", "storefront" ] }, "location_id": { "type": "string", "format": "uuid" }, "default_price_list_id": { "type": "string", "format": "uuid", "nullable": true }, "origins": { "type": "array", "items": { "type": "string" } }, "low_stock_threshold": { "type": "integer", "nullable": true }, "revalidation_url": { "description": "URL de revalidación the backend notifies (MER-4193); storefront only.", "type": "string", "example": "https://tienda.example.com/api/revalidate", "nullable": true, "maxLength": 255 }, "has_revalidation_secret": { "description": "Whether a Secreto de revalidación exists. The secret itself is returned only once, when generated.", "type": "boolean" }, "revalidation_secret_rotated_at": { "description": "When the Secreto de revalidación was last generated (ISO 8601); null without a secret.", "type": "string", "format": "date-time", "example": "2026-10-29T14:00:00+00:00", "nullable": true }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "created_at": { "type": "string", "format": "date-time", "nullable": true }, "updated_at": { "type": "string", "format": "date-time", "nullable": true } }, "type": "object" }, "SalesChannelRevalidationSecretResponse": { "description": "A newly generated Secreto de revalidación (MER-4193). The Vitrina expects it as `Authorization: Bearer `.", "required": [ "secret", "revalidation_secret_rotated_at" ], "properties": { "secret": { "description": "Plaintext bearer, returned only in this response.", "type": "string", "maxLength": 43, "minLength": 43 }, "revalidation_secret_rotated_at": { "type": "string", "format": "date-time", "example": "2026-10-29T14:00:00+00:00" } }, "type": "object" }, "SalesChannelList": { "required": [ "data", "current_page", "last_page", "per_page", "total", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SalesChannel" } }, "current_page": { "type": "integer" }, "last_page": { "description": "1 when the list is empty.", "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "meta": { "required": [ "counts" ], "properties": { "counts": { "required": [ "active", "inactive" ], "properties": { "active": { "type": "integer" }, "inactive": { "type": "integer" } }, "type": "object" } }, "type": "object" } }, "type": "object" }, "SalesChannelProblem": { "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "error_code": { "type": "string", "nullable": true }, "errors": { "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "field_errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "sales_channel_status": { "description": "With sales_channel_status_transition_not_allowed.", "type": "string", "enum": [ "active", "inactive" ] } }, "type": "object" }, "SalesChannelRefusal422": { "description": "A request validation failure or a domain refusal with its error_code.", "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string" }, "error_code": { "type": "string", "nullable": true }, "errors": { "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "field_errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" }, "SalesChannelNotFound404": { "oneOf": [ { "$ref": "#/components/schemas/SalesChannelProblem" }, { "required": [ "message" ], "properties": { "message": { "type": "string" } }, "type": "object" } ] }, "ItemPublicationWriteResponse": { "required": [ "id", "sales_channel_id", "item_id", "published_by", "published_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "sales_channel_id": { "type": "string", "format": "uuid" }, "item_id": { "type": "string", "format": "uuid" }, "published_by": { "type": "string" }, "published_at": { "type": "string", "format": "date-time", "example": "2026-10-15T12:00:00.000000Z" } }, "type": "object" }, "ItemPublicationListItem": { "required": [ "sales_channel_id", "code", "name", "published_at" ], "properties": { "sales_channel_id": { "type": "string", "format": "uuid" }, "code": { "type": "string", "example": "DETAL" }, "name": { "type": "string", "example": "Vitrina detal" }, "published_at": { "type": "string", "format": "date-time", "example": "2026-10-15T12:00:00.000000Z" } }, "type": "object" }, "ItemPublicationList": { "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ItemPublicationListItem" } } }, "type": "object" }, "ItemPublicationProblem": { "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "error_code": { "type": "string", "nullable": true, "enum": [ "channel_not_storefront", "channel_inactive", "item_inactive", "item_not_inventoried", "item_without_primary_image", "item_unpriced", "sales_channel_not_found", "item_not_found" ] }, "errors": { "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" }, "ItemPublicationRefusal422": { "description": "A publication guard refusal with its error_code.", "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string" }, "error_code": { "type": "string", "enum": [ "channel_not_storefront", "channel_inactive", "item_inactive", "item_not_inventoried", "item_without_primary_image", "item_unpriced" ] }, "errors": { "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" }, "ItemPublicationNotFound404": { "oneOf": [ { "$ref": "#/components/schemas/ItemPublicationProblem" }, { "required": [ "message" ], "properties": { "message": { "type": "string" } }, "type": "object" } ] }, "ItemBatchPublicationRequest": { "required": [ "item_ids" ], "properties": { "item_ids": { "description": "Distinct item ids to publish or unpublish.", "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 100, "minItems": 1 } }, "type": "object" }, "ItemBatchPublishResult": { "required": [ "item_id", "outcome", "error_code", "message" ], "properties": { "item_id": { "type": "string", "format": "uuid" }, "outcome": { "type": "string", "enum": [ "published", "already_published", "refused" ] }, "error_code": { "type": "string", "nullable": true, "enum": [ "item_not_found", "item_inactive", "item_not_inventoried", "item_without_primary_image", "item_unpriced", "unexpected_error" ] }, "message": { "type": "string", "nullable": true } }, "type": "object" }, "ItemBatchPublishResponse": { "required": [ "results", "totals" ], "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/ItemBatchPublishResult" } }, "totals": { "required": [ "published", "already_published", "refused" ], "properties": { "published": { "type": "integer" }, "already_published": { "type": "integer" }, "refused": { "type": "integer" } }, "type": "object" } }, "type": "object" }, "ItemBatchUnpublishResult": { "required": [ "item_id", "outcome", "error_code", "message" ], "properties": { "item_id": { "type": "string", "format": "uuid" }, "outcome": { "type": "string", "enum": [ "unpublished", "not_published", "refused" ] }, "error_code": { "type": "string", "nullable": true, "enum": [ "unexpected_error" ] }, "message": { "type": "string", "nullable": true } }, "type": "object" }, "ItemBatchUnpublishResponse": { "required": [ "results", "totals" ], "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/ItemBatchUnpublishResult" } }, "totals": { "required": [ "unpublished", "not_published", "refused" ], "properties": { "unpublished": { "type": "integer" }, "not_published": { "type": "integer" }, "refused": { "type": "integer" } }, "type": "object" } }, "type": "object" }, "ItemBatchPublicationRefusal422": { "oneOf": [ { "$ref": "#/components/schemas/ItemPublicationProblem" }, { "$ref": "#/components/schemas/ItemPublicationRefusal422" } ] }, "ChannelItemPublicationListItem": { "required": [ "item_id", "code", "name", "item_status", "has_primary_image", "published_at", "published_by" ], "properties": { "item_id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "item_status": { "type": "string" }, "has_primary_image": { "type": "boolean" }, "published_at": { "type": "string", "format": "date-time" }, "published_by": { "type": "string" } }, "type": "object" }, "ChannelItemPublicationList": { "required": [ "data", "current_page", "last_page", "per_page", "total" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ChannelItemPublicationListItem" } }, "current_page": { "type": "integer" }, "last_page": { "description": "1 when the list is empty.", "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" } }, "type": "object" }, "SalesInvoiceLiveNote": { "description": "A note of the invoice that is not cancelled, draft included.", "required": [ "id", "code", "kind", "status" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string", "example": "NC2600001" }, "kind": { "type": "string", "enum": [ "credit_note", "debit_note" ] }, "status": { "type": "string", "example": "to_be_approved" } }, "type": "object" }, "SalesInvoiceNote": { "description": "A credit or debit note of the invoice as its detail shows it (MER-3178).", "required": [ "id", "code", "kind", "status", "emission_date", "currency", "total", "balance", "applied_to_invoice" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string", "example": "NC2600001" }, "kind": { "type": "string", "enum": [ "credit_note", "debit_note" ] }, "status": { "description": "A credit note: to_be_approved, with_customer_credit, applied or cancelled. A debit note: to_be_approved, to_be_collected, partially_collected, fully_collected or cancelled.", "type": "string", "example": "applied", "enum": [ "to_be_approved", "with_customer_credit", "applied", "to_be_collected", "partially_collected", "fully_collected", "cancelled" ] }, "emission_date": { "type": "string", "format": "date", "example": "2026-09-16" }, "currency": { "description": "The invoice's document currency.", "type": "string", "example": "USD", "enum": [ "USD", "VES" ] }, "total": { "type": "string", "example": "11.60" }, "balance": { "description": "The note's Open Balance: what a debit note still owes, or the Customer Credit a credit note keeps. 0.00 for a draft or a cancelled note.", "type": "string", "example": "0.00", "nullable": true }, "applied_to_invoice": { "description": "A credit note: what its active applications relieved from this invoice, 0.00 for a draft, a cancelled note or a note on an invoice that owed nothing. Null for a debit note.", "type": "string", "example": "11.60", "nullable": true } }, "type": "object" }, "SalesNoteOriginLine": { "required": [ "id", "item_id", "item_name", "quantity", "unit_price", "discount_percentage", "tax_id", "tax_percentage" ], "properties": { "id": { "type": "string", "format": "uuid" }, "item_id": { "type": "string", "format": "uuid" }, "item_name": { "type": "string" }, "quantity": { "type": "string" }, "unit_price": { "type": "string" }, "discount_percentage": { "type": "string" }, "tax_id": { "type": "string", "format": "uuid" }, "tax_percentage": { "type": "string" } }, "type": "object" }, "SalesNoteOrigin": { "required": [ "id", "code", "company_id", "status", "kind", "customer_name", "emission_date", "accounting_center_id", "invoice_number", "control_number", "currency", "functional_rate", "functional_rate_reference", "reporting_rate", "reporting_rate_reference", "rate_rule", "rate_value_date", "rate_known_at", "rate_origin", "items" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "company_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "kind": { "type": "string" }, "customer_name": { "type": "string", "nullable": true }, "emission_date": { "type": "string", "format": "date" }, "accounting_center_id": { "type": "string", "format": "uuid" }, "invoice_number": { "type": "string", "nullable": true }, "control_number": { "type": "string", "nullable": true }, "currency": { "type": "string" }, "functional_rate": { "type": "string", "nullable": true }, "functional_rate_reference": { "type": "string", "nullable": true }, "reporting_rate": { "type": "string", "nullable": true }, "reporting_rate_reference": { "type": "string", "nullable": true }, "rate_rule": { "type": "string", "nullable": true }, "rate_value_date": { "type": "string", "format": "date", "nullable": true }, "rate_known_at": { "type": "string", "format": "date-time", "nullable": true }, "rate_origin": { "type": "string", "nullable": true }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/SalesNoteOriginLine" } } }, "type": "object" }, "SalesOrderProblem": { "required": [ "title", "status", "detail" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "error_code": { "type": "string", "nullable": true }, "errors": { "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" }, "SalesOrderNativeValidation": { "required": [ "message", "errors" ], "properties": { "message": { "type": "string" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" }, "SalesOrderValidationResponse": { "oneOf": [ { "$ref": "#/components/schemas/SalesOrderProblem" }, { "$ref": "#/components/schemas/SalesOrderNativeValidation" } ] }, "SalesQuoteLineRequest": { "required": [ "id", "category_id", "item_id", "quantity", "unit_id", "unit_price", "tax_id", "tax_percentage", "discount_percentage", "accounting_center_id", "accounting_account_id" ], "properties": { "id": { "description": "Client-supplied line id, distinct within the quote.", "type": "string", "format": "uuid" }, "category_id": { "type": "string", "format": "uuid" }, "item_id": { "type": "string", "format": "uuid" }, "quantity": { "description": "Number or decimal string with at most four fractional digits, from 0.01 to 99999999999.9999, the largest the line stores. A JSON number is read to 14 significant digits; only a decimal string is exact near the upper bound.", "oneOf": [ { "type": "number", "example": 2, "maximum": 99999999999.9999, "minimum": 0.01 }, { "type": "string", "pattern": "^(?:[1-9]\\d{0,10}(?:\\.\\d{1,4})?|0\\.(?:0[1-9]\\d{0,2}|[1-9]\\d{0,3}))$", "example": "2.0000" } ] }, "unit_id": { "type": "string", "format": "uuid" }, "unit_price": { "description": "Number or decimal string with at most two fractional digits, in the quote's currency, from 0 to 9999999999999.99, the largest the line stores. A JSON number is read to 14 significant digits; only a decimal string is exact near the upper bound. The server resolves the line's price from the quote's price list or the item's Precio base on the emission date and stores its price_fingerprint when this price is the proposal; a priced line with another price needs backoffice.sales.price-lists.override (403 sale_price_override_not_allowed). A line's price_fingerprint is never read from the request.", "oneOf": [ { "type": "number", "example": 20, "maximum": 9999999999999.99, "minimum": 0 }, { "type": "string", "pattern": "^0*\\d{1,13}(?:\\.\\d{1,2})?$", "example": "20.00" } ] }, "tax_id": { "description": "An active catalog tax, or the one the line already stores.", "type": "string", "format": "uuid" }, "tax_percentage": { "description": "The catalog rate of the tax: number or decimal string with at most two fractional digits, from 0 to 100.", "oneOf": [ { "type": "number", "example": 16, "maximum": 100, "minimum": 0 }, { "type": "string", "pattern": "^(?:0*(?:[0-9]|[1-9][0-9])(?:\\.[0-9]{1,2})?|0*100(?:\\.0{1,2})?)$", "example": "16.00" } ] }, "discount_percentage": { "description": "Number or decimal string with at most two fractional digits, from 0 to 100.", "oneOf": [ { "type": "number", "example": 5, "maximum": 100, "minimum": 0 }, { "type": "string", "pattern": "^(?:0*(?:[0-9]|[1-9][0-9])(?:\\.[0-9]{1,2})?|0*100(?:\\.0{1,2})?)$", "example": "5.00" } ] }, "accounting_center_id": { "type": "string", "format": "uuid" }, "accounting_account_id": { "type": "string", "format": "uuid" } }, "type": "object" }, "SalesQuoteUpdateRequest": { "description": "A quote is for a client (customer_id) or a prospect (prospect_name and optional contact data), never both.", "required": [ "currency", "emission_date", "valid_until", "payment_term", "accounting_center_id", "accounting_account_receivable_id", "items" ], "properties": { "customer_id": { "description": "A client of the company. Required without prospect_name; prohibits every prospect field.", "type": "string", "format": "uuid", "nullable": true }, "prospect_name": { "description": "Required without customer_id.", "type": "string", "nullable": true, "maxLength": 80, "minLength": 3 }, "prospect_document": { "type": "string", "nullable": true, "maxLength": 30 }, "prospect_phone": { "type": "string", "nullable": true, "maxLength": 30 }, "prospect_email": { "type": "string", "format": "email", "nullable": true, "maxLength": 255 }, "currency": { "type": "string", "enum": [ "USD", "VES" ] }, "emission_date": { "type": "string", "format": "date" }, "valid_until": { "description": "Not before emission_date.", "type": "string", "format": "date" }, "payment_term": { "type": "string", "enum": [ "cash", "five_days", "seven_days", "fifteen_days", "thirty_days" ] }, "accounting_center_id": { "type": "string", "format": "uuid" }, "accounting_account_receivable_id": { "type": "string", "format": "uuid" }, "price_list_id": { "description": "The price list the lines are priced from (MER-3894): a list of the company (else 422 errors.price_list_id), active (else 422 sales_quote_price_list_not_applicable with field_errors.price_list_id). A list in another currency converts at the emission date's document rate; a missing rate resolves as rate_unavailable with no price. A list the quote already holds stays saveable after it is deactivated, including on a currency change. Null or omitted prices the lines from each item's Precio base.", "type": "string", "format": "uuid", "nullable": true }, "reference": { "type": "string", "nullable": true, "maxLength": 255 }, "observations": { "type": "string", "nullable": true }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/SalesQuoteLineRequest" }, "minItems": 1 } }, "type": "object" }, "SalesQuoteCreateRequest": { "description": "A quote is for a client (customer_id) or a prospect (prospect_name and optional contact data), never both.", "required": [ "id", "currency", "emission_date", "valid_until", "payment_term", "accounting_center_id", "accounting_account_receivable_id", "items" ], "properties": { "id": { "description": "Client-supplied quote id.", "type": "string", "format": "uuid" }, "customer_id": { "description": "A client of the company. Required without prospect_name; prohibits every prospect field.", "type": "string", "format": "uuid", "nullable": true }, "prospect_name": { "description": "Required without customer_id.", "type": "string", "nullable": true, "maxLength": 80, "minLength": 3 }, "prospect_document": { "type": "string", "nullable": true, "maxLength": 30 }, "prospect_phone": { "type": "string", "nullable": true, "maxLength": 30 }, "prospect_email": { "type": "string", "format": "email", "nullable": true, "maxLength": 255 }, "currency": { "type": "string", "enum": [ "USD", "VES" ] }, "emission_date": { "type": "string", "format": "date" }, "valid_until": { "description": "Not before emission_date.", "type": "string", "format": "date" }, "payment_term": { "type": "string", "enum": [ "cash", "five_days", "seven_days", "fifteen_days", "thirty_days" ] }, "accounting_center_id": { "type": "string", "format": "uuid" }, "accounting_account_receivable_id": { "type": "string", "format": "uuid" }, "price_list_id": { "description": "The price list the lines are priced from (MER-3894): a list of the company (else 422 errors.price_list_id), active (else 422 sales_quote_price_list_not_applicable with field_errors.price_list_id). A list in another currency converts at the emission date's document rate; a missing rate resolves as rate_unavailable with no price. A list the quote already holds stays saveable after it is deactivated, including on a currency change. Null or omitted prices the lines from each item's Precio base.", "type": "string", "format": "uuid", "nullable": true }, "reference": { "type": "string", "nullable": true, "maxLength": 255 }, "observations": { "type": "string", "nullable": true }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/SalesQuoteLineRequest" }, "minItems": 1 } }, "type": "object" }, "SalesQuoteRejectRequest": { "properties": { "reason": { "description": "Optional; trimmed; a blank reason is stored as none.", "type": "string", "nullable": true, "maxLength": 500 } }, "type": "object" }, "SalesQuoteConvertRequest": { "description": "Converts the quote into a document of the given kind: a sales order (MER-3892) or a direct sales invoice (MER-3893).", "required": [ "target" ], "properties": { "target": { "description": "The kind of document the quote becomes. Any other value answers 422 errors.target.", "type": "string", "enum": [ "sales_order", "sales_invoice" ] }, "customer_id": { "description": "A client of the company. Required for a prospect's quote; a client's quote accepts only its own client, and omitting it keeps that client.", "type": "string", "format": "uuid", "nullable": true }, "location_id": { "description": "Only with sales_invoice: a location of the company the invoice will dispatch from, active or not. Optional; approving the invoice requires it when a line is an inventoried item. With sales_order it answers 422 errors.location_id.", "type": "string", "format": "uuid", "nullable": true }, "emission_date": { "description": "The new document's emission date; the company's today when omitted. The quote's validity is always read against the company's today, never this date.", "type": "string", "format": "date", "nullable": true } }, "type": "object" }, "SalesQuotePriceChange": { "description": "A line quoted at the server's proposal whose price moved since (MER-3894, ADR 0275). The new document keeps quoted_price. Amounts are decimal strings in the quote's currency.", "required": [ "sales_quote_item_id", "quoted_price", "current_price" ], "properties": { "sales_quote_item_id": { "type": "string", "format": "uuid" }, "quoted_price": { "description": "The line's unit_price as quoted, which the new document carries.", "type": "string", "pattern": "^\\d+\\.\\d{2}$", "example": "8.00" }, "current_price": { "description": "The price the line resolves to on the new document's emission date; null when it no longer resolves to one (no tier and no Precio base, no rate of the day, or the resolution was refused).", "type": "string", "pattern": "^\\d+\\.\\d{2}$", "example": "7.50", "nullable": true } }, "type": "object", "additionalProperties": false }, "SalesQuoteConversionResponse": { "required": [ "document_type", "document_id", "code", "price_changes" ], "properties": { "document_type": { "description": "The kind of document the quote became: sales_order or sales_invoice.", "type": "string", "example": "sales_invoice" }, "document_id": { "type": "string", "format": "uuid" }, "code": { "description": "The new document's code.", "type": "string", "example": "INV00042" }, "price_changes": { "description": "Always present, in quote line order: empty when every quoted price still stands or no line was quoted at the server's proposal. A line priced by hand is never resolved nor reported.", "type": "array", "items": { "$ref": "#/components/schemas/SalesQuotePriceChange" } } }, "type": "object" }, "SalesQuoteWriteResponse": { "required": [ "id", "code", "status" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string", "example": "COT2600001" }, "status": { "type": "string", "enum": [ "draft", "sent", "accepted", "rejected", "expired" ] } }, "type": "object" }, "SalesQuoteLabel": { "required": [ "id", "name", "tone", "archived" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "tone": { "type": "string" }, "archived": { "type": "boolean" } }, "type": "object" }, "SalesQuoteLine": { "required": [ "id", "category_id", "item_id", "item_name", "quantity", "unit_id", "unit_price", "subtotal", "tax_id", "tax_percentage", "discount_percentage", "accounting_center_id", "accounting_account_id", "price_fingerprint" ], "properties": { "id": { "type": "string", "format": "uuid" }, "category_id": { "type": "string", "format": "uuid" }, "item_id": { "type": "string", "format": "uuid" }, "item_name": { "description": "The item's name when it was quoted.", "type": "string" }, "quantity": { "type": "string", "pattern": "^\\d+\\.\\d{4}$", "example": "2.0000" }, "unit_id": { "type": "string", "format": "uuid" }, "unit_price": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "example": "20.00" }, "subtotal": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "example": "40.00" }, "tax_id": { "type": "string", "format": "uuid" }, "tax_percentage": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "example": "16.00" }, "discount_percentage": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "example": "5.00" }, "accounting_center_id": { "type": "string", "format": "uuid" }, "accounting_account_id": { "type": "string", "format": "uuid" }, "price_fingerprint": { "description": "The Huella de precio of unit_price when it was the server's proposal on saving: from the quote's price list, or the item's Precio base when the quote has no list (MER-3894, ADR 0272). Null for a price the user set, or a line with no price to propose. Only the server sets it; a conversion compares it to report price_changes.", "type": "string", "pattern": "^[a-f0-9]{64}$", "nullable": true } }, "type": "object" }, "SalesQuote": { "required": [ "id", "code", "status", "customer_id", "customer_name", "prospect_name", "prospect_document", "prospect_phone", "prospect_email", "currency", "emission_date", "valid_until", "payment_term", "accounting_center_id", "accounting_account_receivable_id", "price_list_id", "price_list_name", "reference", "observations", "subtotal", "discount", "taxes", "total", "sent_at", "responded_at", "rejection_reason", "converted_document_type", "converted_document_id", "converted_document_code", "labels", "items", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string", "example": "COT2600001" }, "status": { "type": "string", "enum": [ "draft", "sent", "accepted", "rejected", "expired" ] }, "customer_id": { "type": "string", "format": "uuid", "nullable": true }, "customer_name": { "description": "Null for a prospect.", "type": "string", "nullable": true }, "prospect_name": { "type": "string", "nullable": true }, "prospect_document": { "type": "string", "nullable": true }, "prospect_phone": { "type": "string", "nullable": true }, "prospect_email": { "type": "string", "nullable": true }, "currency": { "type": "string", "enum": [ "USD", "VES" ] }, "emission_date": { "type": "string", "format": "date" }, "valid_until": { "type": "string", "format": "date" }, "payment_term": { "type": "string", "enum": [ "cash", "five_days", "seven_days", "fifteen_days", "thirty_days" ] }, "accounting_center_id": { "type": "string", "format": "uuid" }, "accounting_account_receivable_id": { "type": "string", "format": "uuid" }, "price_list_id": { "type": "string", "format": "uuid", "nullable": true }, "price_list_name": { "description": "The name of the quote's price list, shown even after the list is deactivated and to whoever cannot read price lists (MER-3894); null without one.", "type": "string", "example": "Precios al mayor", "nullable": true }, "reference": { "type": "string", "nullable": true }, "observations": { "type": "string", "nullable": true }, "subtotal": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "example": "40.00" }, "discount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "example": "2.00" }, "taxes": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "example": "6.08" }, "total": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "example": "44.08" }, "sent_at": { "description": "When the quote was sent: set while it is sent and after it is rejected or expired; null on a draft, a reopened one included.", "type": "string", "format": "date-time", "nullable": true }, "responded_at": { "description": "When the client's answer was recorded: the client's rejection, or its acceptance by conversion; null while the quote awaits an answer.", "type": "string", "format": "date-time", "nullable": true }, "rejection_reason": { "description": "The reason given when the quote was rejected, if any.", "type": "string", "nullable": true }, "converted_document_type": { "description": "The kind of document the quote converted into: sales_order or sales_invoice. Null until the quote converts.", "type": "string", "example": "sales_order", "nullable": true }, "converted_document_id": { "description": "The document the quote converted into; null until it converts.", "type": "string", "format": "uuid", "nullable": true }, "converted_document_code": { "description": "That document's code; null until the quote converts.", "type": "string", "example": "SOR2600012", "nullable": true }, "labels": { "type": "array", "items": { "$ref": "#/components/schemas/SalesQuoteLabel" } }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/SalesQuoteLine" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "SalesQuoteListItem": { "required": [ "id", "code", "status", "customer_id", "customer_name", "prospect_name", "currency", "emission_date", "valid_until", "payment_term", "reference", "subtotal", "discount", "taxes", "total", "labels", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string", "example": "COT2600001" }, "status": { "type": "string", "enum": [ "draft", "sent", "accepted", "rejected", "expired" ] }, "customer_id": { "type": "string", "format": "uuid", "nullable": true }, "customer_name": { "type": "string", "nullable": true }, "prospect_name": { "type": "string", "nullable": true }, "currency": { "type": "string", "enum": [ "USD", "VES" ] }, "emission_date": { "type": "string", "format": "date" }, "valid_until": { "type": "string", "format": "date" }, "payment_term": { "type": "string", "enum": [ "cash", "five_days", "seven_days", "fifteen_days", "thirty_days" ] }, "reference": { "type": "string", "nullable": true }, "subtotal": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "discount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "taxes": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "total": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "labels": { "type": "array", "items": { "$ref": "#/components/schemas/SalesQuoteLabel" } }, "created_at": { "type": "string", "format": "date-time", "nullable": true }, "updated_at": { "type": "string", "format": "date-time", "nullable": true } }, "type": "object" }, "SalesQuoteList": { "required": [ "data", "current_page", "last_page", "per_page", "total", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SalesQuoteListItem" } }, "current_page": { "type": "integer" }, "last_page": { "description": "0 when the list is empty.", "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "meta": { "required": [ "counts" ], "properties": { "counts": { "description": "Quotes per status (draft, sent, accepted, rejected, expired), every status present, under the same filters but the status one.", "type": "object", "additionalProperties": { "type": "integer" } } }, "type": "object" } }, "type": "object" }, "SalesQuoteProblem": { "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "error_code": { "type": "string", "nullable": true }, "errors": { "description": "Request validation messages by field.", "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "field_errors": { "description": "A domain refusal's messages by request field, such as items.0.tax_id.", "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "tax_ids": { "description": "With sales_quote_tax_selection_invalid: the refused taxes.", "type": "array", "items": { "type": "string", "format": "uuid" } }, "quote_status": { "description": "With sales_quote_not_editable, sales_quote_invalid_transition, sales_quote_already_converted, sales_quote_expired or sales_quote_not_convertible: the quote's status.", "type": "string", "enum": [ "draft", "sent", "accepted", "rejected", "expired" ] }, "target_status": { "description": "With sales_quote_invalid_transition: the status the request asked for.", "type": "string", "enum": [ "draft", "sent", "accepted", "rejected", "expired" ] }, "valid_until": { "description": "With sales_quote_expired: the last day the quote held its prices.", "type": "string", "format": "date" }, "converted_document_type": { "description": "With sales_quote_already_converted: the kind of document the quote became, sales_order or sales_invoice.", "type": "string", "example": "sales_order" }, "converted_document_id": { "description": "With sales_quote_already_converted: the document the quote became.", "type": "string", "format": "uuid" } }, "type": "object" }, "SalesQuoteLegacyRefusal": { "description": "Rendered outside the Problem body: for totals beyond storage (sales_invoice_total_exceeds_storage) and, converting into a sales invoice, for a quoted tax inactivated since quoting (sales_invoice_tax_selection_invalid, with tax_ids).", "required": [ "error", "detail" ], "properties": { "error": { "type": "string" }, "detail": { "type": "string" }, "tax_ids": { "description": "With sales_invoice_tax_selection_invalid: the refused taxes.", "type": "array", "items": { "type": "string", "format": "uuid" } } }, "type": "object" }, "SalesQuoteRefusal422": { "oneOf": [ { "$ref": "#/components/schemas/SalesQuoteProblem" }, { "$ref": "#/components/schemas/SalesQuoteLegacyRefusal" } ] }, "SalesQuoteInvoiceCounterpartyRefusal": { "description": "Rendered outside the Problem body when a quote converts into a sales invoice for a client the company cannot invoice: the company has an active fiscal profile and the client is unknown or misses fiscal fields (sales_invoice_counterparty_not_invoiceable).", "required": [ "error_code", "detail", "client_id", "reason", "missing" ], "properties": { "error_code": { "type": "string", "example": "sales_invoice_counterparty_not_invoiceable" }, "detail": { "type": "string" }, "client_id": { "type": "string", "format": "uuid" }, "reason": { "type": "string", "enum": [ "not_found", "fiscal_identity_incomplete" ] }, "missing": { "description": "The client's fiscal fields still missing; empty when the client is not found.", "type": "array", "items": { "type": "string" } } }, "type": "object" }, "SalesQuoteConvertRefusal422": { "oneOf": [ { "$ref": "#/components/schemas/SalesQuoteProblem" }, { "$ref": "#/components/schemas/SalesQuoteLegacyRefusal" }, { "$ref": "#/components/schemas/SalesQuoteInvoiceCounterpartyRefusal" } ] }, "SalesQuoteMiddlewareNotFound": { "description": "Answered before the controller runs: by the tenancy middleware for an unknown company, or by the API key guardrails for a key bound to another company.", "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Recurso no encontrado" } }, "type": "object" }, "SalesQuoteNotFound404": { "oneOf": [ { "$ref": "#/components/schemas/SalesQuoteProblem" }, { "$ref": "#/components/schemas/SalesQuoteMiddlewareNotFound" } ] }, "WebOrderNoticeRow": { "required": [ "id", "web_order_id", "order_display_id", "kind", "channel", "status", "safe_code", "attempt_count", "generation", "planned_at", "due_at", "first_attempted_at", "next_attempt_at", "updated_at", "resendable" ], "properties": { "id": { "description": "Pedido web notice API components (MER-5442). No schema has a member for a destination,\na body, a variable, an idempotency key, an attempt token, a provider id, the frozen\nrequest or its digest. Instants are UTC ISO 8601. A refusal's data travels beside the\nfive Problem members: `status` belongs to the envelope, so the notice's is `notice_status`.", "type": "string", "format": "uuid" }, "web_order_id": { "type": "string", "format": "uuid" }, "order_display_id": { "type": "string" }, "kind": { "type": "string", "enum": [ "reserved", "expiry_reminder", "expired", "approved", "rejected" ] }, "channel": { "type": "string", "enum": [ "whatsapp", "email" ] }, "status": { "description": "accepted is the provider's receipt, distinct from delivered; unknown means the provider may hold it and it is never resent blindly.", "type": "string", "enum": [ "pending", "sending", "accepted", "delivered", "undelivered", "unknown", "blocked", "dead_letter", "skipped" ] }, "safe_code": { "description": "Why it stopped or waits. On skipped: not_consented, consent_withdrawn, no_destination, destination_changed, channel_disabled, obsolete. Otherwise: template_unavailable, channel_unconfigured, frozen_request_mismatch, provider_rejected, retries_exhausted, no_response, lease_expired, replay_horizon_reached, replay_budget_spent, idempotency_key_reused, lookup_unresolved, provider_failed.", "type": "string", "nullable": true }, "attempt_count": { "description": "Every attempt ever made, across generations; the resend's expected_attempt_count.", "type": "integer" }, "generation": { "description": "1, plus one per manual resend.", "type": "integer" }, "planned_at": { "type": "string", "format": "date-time" }, "due_at": { "type": "string", "format": "date-time" }, "first_attempted_at": { "description": "The first attempt of the current generation.", "type": "string", "format": "date-time", "nullable": true }, "next_attempt_at": { "description": "Only for pending, or unknown with a scheduled replay or lookup; never a sending lease.", "type": "string", "format": "date-time", "nullable": true }, "updated_at": { "type": "string", "format": "date-time" }, "resendable": { "description": "dead_letter or blocked, and no attempt its provider may hold.", "type": "boolean" } }, "type": "object" }, "WebOrderNoticePage": { "required": [ "data", "current_page", "last_page", "per_page", "total" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebOrderNoticeRow" } }, "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" } }, "type": "object" }, "WebOrderNoticeAttempt": { "required": [ "ordinal", "generation", "outcome", "provider_status", "safe_code", "started_at", "completed_at" ], "properties": { "ordinal": { "type": "integer" }, "generation": { "type": "integer" }, "outcome": { "description": "What the send answered; null when no response was recorded.", "type": "string", "nullable": true, "enum": [ "accepted", "refused", "rejected", "unknown" ] }, "provider_status": { "description": "Later evidence from a signed callback or a lookup.", "type": "string", "nullable": true, "enum": [ "accepted", "delivered", "undelivered" ] }, "safe_code": { "description": "A provider detail such as http_429, twilio_20429, twilio_63016, resend_rate_limit_exceeded, timeout, connect_failed, server_error or gateway_error.", "type": "string", "nullable": true }, "started_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": "string", "format": "date-time", "nullable": true } }, "type": "object" }, "WebOrderNoticeRequeue": { "required": [ "generation", "requested_by", "reason", "requested_at" ], "properties": { "generation": { "description": "The generation this resend opened.", "type": "integer" }, "requested_by": { "required": [ "id", "name" ], "properties": { "id": { "type": "integer" }, "name": { "description": "Null once the user is deleted.", "type": "string", "nullable": true } }, "type": "object" }, "reason": { "type": "string", "nullable": true }, "requested_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "WebOrderNoticeDetail": { "allOf": [ { "$ref": "#/components/schemas/WebOrderNoticeRow" }, { "required": [ "template_version", "prepared_at", "generation_attempt_count", "max_attempts", "provider_confirmed", "attempts", "requeues" ], "properties": { "template_version": { "type": "integer" }, "prepared_at": { "description": "When its request froze.", "type": "string", "format": "date-time", "nullable": true }, "generation_attempt_count": { "type": "integer" }, "max_attempts": { "description": "Attempts per generation.", "type": "integer" }, "provider_confirmed": { "description": "Whether a provider returned an id for one of its attempts; the id itself is never shown.", "type": "boolean" }, "attempts": { "type": "array", "items": { "$ref": "#/components/schemas/WebOrderNoticeAttempt" } }, "requeues": { "type": "array", "items": { "$ref": "#/components/schemas/WebOrderNoticeRequeue" } } }, "type": "object" } ] }, "WebOrderNoticeResendRequest": { "required": [ "idempotency_key", "expected_attempt_count" ], "properties": { "idempotency_key": { "description": "The same key, body and actor replay the stored answer.", "type": "string", "pattern": "^[A-Za-z0-9._:-]{8,128}$", "maxLength": 128, "minLength": 8 }, "expected_attempt_count": { "description": "The attempt_count the operator saw.", "type": "integer", "maximum": 255, "minimum": 0 }, "reason": { "description": "Staff-only; never sent to the buyer.", "type": "string", "nullable": true, "maxLength": 280 } }, "type": "object" }, "WebOrderNoticeProblem": { "description": "A refusal. A non-null error_code names a controller refusal, and the data it carries sits beside the standard members. The permission middleware answers the same envelope with error_code null, and the tenant middleware answers only title, status and detail.", "required": [ "title", "status", "detail" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "error_code": { "type": "string", "nullable": true }, "errors": { "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "notice_status": { "description": "With web_order_notice_not_resendable.", "type": "string" }, "current_attempt_count": { "description": "With web_order_notice_version_conflict.", "type": "integer" } }, "type": "object" }, "WebOrderQueueClaim": { "required": [ "cycle_id", "claimed_by_user_id", "claimed_at", "shift_id" ], "properties": { "cycle_id": { "description": "New for every claim, never repeated. Return and release send it back to prove which claim the till saw.", "type": "string", "format": "uuid" }, "claimed_by_user_id": { "type": "integer" }, "claimed_at": { "type": "string", "format": "date-time" }, "shift_id": { "description": "The Turno that was open when it was taken.", "type": "string", "format": "uuid" } }, "type": "object" }, "WebOrderQueueRowClaim": { "required": [ "cycle_id", "claimed_by_user_id", "claimed_by_name", "claimed_at", "shift_id", "shift_closed" ], "properties": { "cycle_id": { "type": "string", "format": "uuid" }, "claimed_by_user_id": { "type": "integer" }, "claimed_by_name": { "type": "string", "nullable": true }, "claimed_at": { "type": "string", "format": "date-time" }, "shift_id": { "type": "string", "format": "uuid" }, "shift_closed": { "description": "True when the Turno that took it is closed; a seller on an open Turno may take it over. A read, checked again by the takeover.", "type": "boolean" } }, "type": "object", "nullable": true }, "WebOrderQueueMerchandise": { "required": [ "line_count", "first_item_name", "total" ], "properties": { "line_count": { "type": "integer" }, "first_item_name": { "type": "string", "nullable": true }, "total": { "description": "Null only on an order whose stored terms hold no total.", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/WebOrderMoney" } ] } }, "type": "object" }, "WebOrderQueueRow": { "required": [ "id", "display_id", "status", "version", "expires_at", "review_due_at", "buyer", "merchandise", "claim", "review_url" ], "properties": { "id": { "type": "string", "format": "uuid" }, "display_id": { "type": "string", "example": "WEB-0199E97300007000800000000000A001" }, "status": { "description": "The inbox lists awaiting_payment and payment_reported; the detail reads any status.", "type": "string", "enum": [ "awaiting_payment", "payment_reported", "approved", "rejected", "cancelled", "expired", "charged_in_store" ] }, "version": { "description": "The expected_version a claim or a release sends. A claim or a return never moves it.", "type": "integer" }, "expires_at": { "description": "Fixed at reserve. Till activity never moves it, and a reported order keeps it.", "type": "string", "format": "date-time" }, "review_due_at": { "type": "string", "format": "date-time", "nullable": true }, "buyer": { "required": [ "name" ], "properties": { "name": { "type": "string", "nullable": true } }, "type": "object" }, "merchandise": { "$ref": "#/components/schemas/WebOrderQueueMerchandise" }, "claim": { "$ref": "#/components/schemas/WebOrderQueueRowClaim" }, "review_url": { "description": "Non-null only for payment_reported with a configured frontend. A cashier without backoffice.sales.web-orders.view gets a refusal there, so a POS may condition its display on the session's permissions.", "type": "string", "nullable": true } }, "type": "object" }, "WebOrderQueuePage": { "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebOrderQueueRow" } }, "meta": { "required": [ "total", "per_page", "current_page" ], "properties": { "total": { "type": "integer" }, "per_page": { "type": "integer" }, "current_page": { "type": "integer" } }, "type": "object" } }, "type": "object" }, "WebOrderChargedSale": { "description": "The Venta de mostrador that charged a Pedido web (MER-5432). Any seller reads its code; a till offers the receipt only to the seller who charged it or a holder of backoffice.sales.counter-sales.view, since the receipt keeps its own gate.", "required": [ "id", "code", "charged_by_user_id", "charged_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "description": "The code the sale shows.", "type": "string", "example": "0ABC12" }, "charged_by_user_id": { "type": "integer" }, "charged_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "WebOrderQueueDetail": { "allOf": [ { "$ref": "#/components/schemas/WebOrderQueueRow" }, { "required": [ "created_at", "terms", "charged_sale" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "terms": { "$ref": "#/components/schemas/WebOrderPublicTerms" }, "charged_sale": { "description": "The sale that charged it; null on any other status. The inbox row never carries it.", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/WebOrderChargedSale" } ] } }, "type": "object" } ] }, "WebOrderClaimRequest": { "required": [ "cash_register_id", "expected_version", "idempotency_key" ], "properties": { "cash_register_id": { "type": "string", "format": "uuid" }, "expected_version": { "description": "The version the till read. Any other answers web_order_version_conflict.", "type": "integer", "minimum": 1 }, "idempotency_key": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{8,128}$", "example": "claim-0001-abcd", "maxLength": 128, "minLength": 8 } }, "type": "object" }, "WebOrderReturnRequest": { "required": [ "cash_register_id", "claim_cycle_id", "idempotency_key" ], "properties": { "cash_register_id": { "type": "string", "format": "uuid" }, "claim_cycle_id": { "description": "The claim the till saw. Any other answers web_order_claim_conflict.", "type": "string", "format": "uuid" }, "idempotency_key": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{8,128}$", "example": "return-0001-abcd", "maxLength": 128, "minLength": 8 } }, "type": "object" }, "WebOrderReleaseRequest": { "required": [ "cash_register_id", "expected_version", "claim_cycle_id", "idempotency_key" ], "properties": { "cash_register_id": { "type": "string", "format": "uuid" }, "expected_version": { "description": "The version the till read. Any other answers web_order_version_conflict.", "type": "integer", "minimum": 1 }, "claim_cycle_id": { "description": "Must be sent. The claim the till saw, or null when it saw the order unclaimed. Anything else answers web_order_claim_conflict.", "type": "string", "format": "uuid", "nullable": true }, "idempotency_key": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{8,128}$", "example": "release-0001-abcd", "maxLength": 128, "minLength": 8 }, "reason": { "description": "Staff-only, up to 280 characters. It never reaches the buyer.", "type": "string", "nullable": true, "maxLength": 280 } }, "type": "object" }, "WebOrderTakeOverRequest": { "required": [ "cash_register_id", "expected_version", "claim_cycle_id", "idempotency_key" ], "properties": { "cash_register_id": { "type": "string", "format": "uuid" }, "expected_version": { "description": "The version the till read. Any other answers web_order_version_conflict.", "type": "integer", "minimum": 1 }, "claim_cycle_id": { "description": "The claim the till saw on a closed Turno. Any other answers web_order_claim_conflict.", "type": "string", "format": "uuid" }, "idempotency_key": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{8,128}$", "example": "takeover-0001-abcd", "maxLength": 128, "minLength": 8 } }, "type": "object" }, "WebOrderQueueCommandResult": { "description": "What claim, take-over, return and release answer, byte-identical on every replay. It carries no claimant name, so the till reads the inbox again after a command.", "required": [ "id", "display_id", "status", "version", "expires_at", "claim" ], "properties": { "id": { "type": "string", "format": "uuid" }, "display_id": { "type": "string" }, "status": { "description": "cancelled after a release, awaiting_payment otherwise.", "type": "string", "enum": [ "awaiting_payment", "cancelled" ] }, "version": { "type": "integer" }, "expires_at": { "type": "string", "format": "date-time" }, "claim": { "description": "Null after a return or a release.", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/WebOrderQueueClaim" } ] } }, "type": "object" }, "WebOrderQueueProblem": { "description": "A refusal. A non-null error_code names a controller refusal, and the data it carries sits beside the standard members. The permission middleware answers the same envelope with error_code null, and the tenant middleware answers only title, status and detail.", "required": [ "title", "status", "detail" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "error_code": { "type": "string", "nullable": true }, "errors": { "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "order_status": { "description": "With a refusal about the order.", "type": "string" }, "current_version": { "description": "With a refusal about the order.", "type": "integer" }, "expires_at": { "description": "With a refusal about the order.", "type": "string", "format": "date-time" }, "claim": { "description": "With a refusal about the order: the claim it holds now.", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/WebOrderQueueClaim" } ] }, "cash_register_id": { "description": "With cash_shift_not_open.", "type": "string", "format": "uuid" }, "reason": { "description": "With counter_sale_cash_register_not_selling.", "type": "string", "enum": [ "cash_register_inactive", "no_sales_channel", "sales_channel_not_found", "sales_channel_inactive", "sales_channel_not_pos" ] }, "charged_sale": { "description": "With web_order_already_charged: the sale that charged it.", "allOf": [ { "$ref": "#/components/schemas/WebOrderChargedSale" } ] }, "missing": { "description": "With client_fiscal_identity_incomplete: what the Client lacks, and never who it is. client when the order has no Client.", "type": "array", "items": { "type": "string", "enum": [ "client", "document", "legal_name", "fiscal_address", "vat_taxpayer_type", "islr_person_type" ] } } }, "type": "object" }, "WebOrderMoney": { "required": [ "amount", "currency" ], "properties": { "amount": { "description": "Pedidos web review and recovery API components (MER-5429, MER-5430). Decimal amounts are strings. A\nrefusal's data travels beside the five Problem members: `status` belongs to the\nenvelope, so the order's status is `order_status`.", "type": "string", "example": "1000.00" }, "currency": { "type": "string", "example": "VES" } }, "type": "object" }, "WebOrderReviewRow": { "required": [ "id", "display_id", "status", "version", "client", "total", "rail", "reported_at", "review_due_at", "is_review_overdue", "has_attention", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "display_id": { "type": "string" }, "status": { "type": "string", "enum": [ "awaiting_payment", "payment_reported", "approved", "rejected", "cancelled", "expired", "charged_in_store" ] }, "version": { "type": "integer" }, "client": { "required": [ "id", "name" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "type": "object", "nullable": true }, "total": { "$ref": "#/components/schemas/WebOrderMoney" }, "rail": { "required": [ "id", "name", "currency" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "currency": { "type": "string" } }, "type": "object", "nullable": true }, "reported_at": { "description": "When the active report arrived.", "type": "string", "format": "date-time", "nullable": true }, "review_due_at": { "description": "Fixed at the first report; a correction never moves it.", "type": "string", "format": "date-time", "nullable": true }, "is_review_overdue": { "description": "True only for payment_reported past its deadline.", "type": "boolean" }, "has_attention": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "WebOrderReviewPage": { "required": [ "data", "current_page", "last_page", "per_page", "total", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebOrderReviewRow" } }, "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "meta": { "required": [ "counts" ], "properties": { "counts": { "description": "The company's orders by status, zero-filled, under no filter.", "required": [ "awaiting_payment", "payment_reported", "approved", "rejected", "cancelled", "expired", "charged_in_store" ], "properties": { "awaiting_payment": { "type": "integer" }, "payment_reported": { "type": "integer" }, "approved": { "type": "integer" }, "rejected": { "type": "integer" }, "cancelled": { "type": "integer" }, "expired": { "type": "integer" }, "charged_in_store": { "type": "integer" } }, "type": "object" } }, "type": "object" } }, "type": "object" }, "WebOrderReviewDocument": { "required": [ "id", "code", "status" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "status": { "type": "string" } }, "type": "object", "nullable": true }, "WebOrderReviewDetail": { "required": [ "id", "display_id", "status", "version", "created_at", "expires_at", "channel_id", "location_id", "client", "buyer_contact", "frozen_terms", "settlement", "review", "payment_reports", "attention", "decision", "documents" ], "properties": { "id": { "type": "string", "format": "uuid" }, "display_id": { "type": "string" }, "status": { "type": "string", "enum": [ "awaiting_payment", "payment_reported", "approved", "rejected", "cancelled", "expired", "charged_in_store" ] }, "version": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" }, "channel_id": { "type": "string", "format": "uuid" }, "location_id": { "type": "string", "format": "uuid" }, "client": { "required": [ "id", "name", "invoiceable", "missing" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "invoiceable": { "type": "boolean" }, "missing": { "description": "Counterparty fiscal fields approval would refuse for: document, legal_name, fiscal_address, vat_taxpayer_type, islr_person_type; or client when the Client is unknown.", "type": "array", "items": { "type": "string" } } }, "type": "object", "nullable": true }, "buyer_contact": { "description": "How to reach the buyer about this order. Null for a requester without backoffice.sales.web-orders.review.", "required": [ "phone" ], "properties": { "phone": { "description": "The E.164 number she verified. Null until she verifies again, or when the stored value can no longer be read as one.", "type": "string", "pattern": "^\\+[1-9][0-9]{6,14}$", "nullable": true } }, "type": "object", "nullable": true }, "frozen_terms": { "required": [ "currency", "lines", "totals", "document_rate", "rail" ], "properties": { "currency": { "type": "string" }, "lines": { "type": "array", "items": { "required": [ "id", "item_id", "item_name", "quantity", "unit_id", "unit_price", "tax_id", "tax_percentage", "discount_percentage", "is_inventoried" ], "properties": { "id": { "type": "string", "format": "uuid" }, "item_id": { "type": "string", "format": "uuid" }, "item_name": { "type": "string" }, "quantity": { "type": "string" }, "unit_id": { "type": "string", "format": "uuid" }, "unit_price": { "type": "string" }, "tax_id": { "type": "string", "format": "uuid" }, "tax_percentage": { "type": "string" }, "discount_percentage": { "type": "string" }, "is_inventoried": { "type": "boolean" } }, "type": "object" } }, "totals": { "required": [ "subtotal", "taxes", "total", "counterpart" ], "properties": { "subtotal": { "$ref": "#/components/schemas/WebOrderMoney" }, "taxes": { "$ref": "#/components/schemas/WebOrderMoney" }, "total": { "$ref": "#/components/schemas/WebOrderMoney" }, "counterpart": { "required": [ "currency", "subtotal", "taxes", "total" ], "properties": { "currency": { "type": "string" }, "subtotal": { "type": "string" }, "taxes": { "type": "string" }, "total": { "type": "string" } }, "type": "object", "nullable": true } }, "type": "object" }, "document_rate": { "required": [ "currency", "functional_rate", "reporting_rate", "rate_rule", "rate_value_date", "rate_known_at", "rate_origin" ], "properties": { "currency": { "type": "string" }, "functional_rate": { "type": "string" }, "reporting_rate": { "type": "string" }, "rate_rule": { "type": "string" }, "rate_value_date": { "type": "string", "format": "date" }, "rate_known_at": { "type": "string", "format": "date-time", "nullable": true }, "rate_origin": { "type": "string", "nullable": true } }, "type": "object", "nullable": true }, "rail": { "required": [ "id", "name", "class", "currency", "requires_reference", "settle_amount", "settlement_rate" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "class": { "type": "string" }, "currency": { "type": "string" }, "requires_reference": { "type": "boolean" }, "settle_amount": { "$ref": "#/components/schemas/WebOrderMoney" }, "settlement_rate": { "description": "The rate that made settle_amount. Null for a rail in the document currency, and on orders reserved before MER-5429.", "required": [ "rate", "value_date" ], "properties": { "rate": { "type": "string" }, "value_date": { "type": "string", "format": "date" } }, "type": "object", "nullable": true } }, "type": "object", "nullable": true } }, "type": "object" }, "settlement": { "required": [ "is_cross_currency", "frozen_rate_available", "reviewer_may_agree_settlement_rate" ], "properties": { "is_cross_currency": { "type": "boolean" }, "frozen_rate_available": { "type": "boolean" }, "reviewer_may_agree_settlement_rate": { "type": "boolean" } }, "type": "object" }, "review": { "required": [ "company_today", "review_due_at", "is_overdue" ], "properties": { "company_today": { "description": "The default the UI proposes for document_date and the cap for both dates. cash_date has no server default.", "type": "string", "format": "date" }, "review_due_at": { "type": "string", "format": "date-time", "nullable": true }, "is_overdue": { "type": "boolean" } }, "type": "object" }, "payment_reports": { "type": "array", "items": { "required": [ "id", "ordinal", "reference", "reason", "reported_at", "active", "evidence_mime" ], "properties": { "id": { "type": "string", "format": "uuid" }, "ordinal": { "type": "integer" }, "reference": { "type": "string" }, "reason": { "type": "string", "nullable": true }, "reported_at": { "type": "string", "format": "date-time" }, "active": { "type": "boolean" }, "evidence_mime": { "type": "string" } }, "type": "object" } }, "attention": { "required": [ "reason", "by_user_id", "by_name", "at" ], "properties": { "reason": { "type": "string" }, "by_user_id": { "type": "integer" }, "by_name": { "type": "string", "nullable": true }, "at": { "type": "string", "format": "date-time" } }, "type": "object", "nullable": true }, "decision": { "required": [ "kind", "decided_at", "decided_by_user_id", "decided_by_name", "reason", "no_money_received" ], "properties": { "kind": { "type": "string", "enum": [ "approved", "rejected" ] }, "decided_at": { "type": "string", "format": "date-time" }, "decided_by_user_id": { "type": "integer" }, "decided_by_name": { "type": "string", "nullable": true }, "reason": { "type": "string", "nullable": true }, "no_money_received": { "type": "boolean" } }, "type": "object", "nullable": true }, "documents": { "required": [ "invoice", "collection", "dispatch" ], "properties": { "invoice": { "$ref": "#/components/schemas/WebOrderReviewDocument" }, "collection": { "$ref": "#/components/schemas/WebOrderReviewDocument" }, "dispatch": { "description": "Null for an order with no inventoried line.", "allOf": [ { "$ref": "#/components/schemas/WebOrderReviewDocument" } ] } }, "type": "object" } }, "type": "object" }, "WebOrderApproveRequest": { "required": [ "idempotency_key", "version", "document_date", "cash_date", "currency", "amount" ], "properties": { "idempotency_key": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{8,128}$", "example": "rev-0001-abcd", "maxLength": 128, "minLength": 8 }, "version": { "description": "The version the reviewer read. A correction since then answers web_order_version_conflict.", "type": "integer", "minimum": 1 }, "document_date": { "description": "The invoice's emission day, at most review.company_today.", "type": "string", "format": "date", "example": "2026-11-03" }, "cash_date": { "description": "The day the money arrived, at most review.company_today. Never the reservation day by default.", "type": "string", "format": "date", "example": "2026-11-02" }, "currency": { "description": "The currency of the money observed.", "type": "string", "enum": [ "USD", "VES" ] }, "amount": { "description": "The money observed: positive, up to 13 integer digits and 2 decimals. It must be exactly frozen_terms.rail.settle_amount.", "type": "string", "pattern": "^\\d{1,13}(\\.\\d{1,2})?$", "example": "10.00" } }, "type": "object" }, "WebOrderRejectRequest": { "required": [ "idempotency_key", "version", "reason", "no_money_received" ], "properties": { "idempotency_key": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{8,128}$", "example": "rev-0002-abcd", "maxLength": 128, "minLength": 8 }, "version": { "description": "The version the reviewer read. A correction since then answers web_order_version_conflict.", "type": "integer", "minimum": 1 }, "reason": { "description": "1 to 200 characters once trimmed.", "type": "string", "maxLength": 200, "minLength": 1 }, "no_money_received": { "description": "Must be exactly true: the reviewer attests that no money arrived.", "type": "boolean", "enum": [ true ] } }, "type": "object" }, "WebOrderAttentionRequest": { "required": [ "reason" ], "properties": { "reason": { "description": "1 to 200 characters once trimmed.", "type": "string", "maxLength": 200, "minLength": 1 } }, "type": "object" }, "WebOrderDecisionResponse": { "required": [ "id", "status", "version", "decision", "invoice_id", "collection_id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "approved", "rejected" ] }, "version": { "type": "integer" }, "decision": { "required": [ "kind", "decided_at", "decided_by_user_id", "reason", "no_money_received" ], "properties": { "kind": { "type": "string", "enum": [ "approved", "rejected" ] }, "decided_at": { "type": "string", "format": "date-time" }, "decided_by_user_id": { "type": "integer" }, "reason": { "type": "string", "nullable": true }, "no_money_received": { "type": "boolean" } }, "type": "object" }, "invoice_id": { "type": "string", "format": "uuid", "nullable": true }, "collection_id": { "type": "string", "format": "uuid", "nullable": true } }, "type": "object" }, "WebOrderAttentionResponse": { "required": [ "id", "status", "version", "attention" ], "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "version": { "type": "integer" }, "attention": { "required": [ "reason", "by_user_id", "at" ], "properties": { "reason": { "type": "string" }, "by_user_id": { "type": "integer" }, "at": { "type": "string", "format": "date-time" } }, "type": "object" } }, "type": "object" }, "WebOrderLeftoverRow": { "required": [ "id", "display_id", "kind", "status", "version", "expires_at", "open_reservations" ], "properties": { "id": { "type": "string", "format": "uuid" }, "display_id": { "type": "string" }, "kind": { "description": "leftover: an ended order still holding stock, which release-leftovers lets go of. overdue: awaiting payment past its deadline, which the expiry job will expire.", "type": "string", "enum": [ "leftover", "overdue" ] }, "status": { "type": "string", "enum": [ "awaiting_payment", "expired", "rejected", "cancelled" ] }, "version": { "type": "integer" }, "expires_at": { "type": "string", "format": "date-time" }, "open_reservations": { "description": "Active Reservas no dispatch line claimed.", "type": "integer" } }, "type": "object" }, "WebOrderLeftoversList": { "required": [ "data", "has_more" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebOrderLeftoverRow" } }, "has_more": { "description": "Either kind passed its limit of 100 rows.", "type": "boolean" } }, "type": "object" }, "WebOrderLeftoversReleased": { "required": [ "id", "status", "version", "released_reservations" ], "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "expired", "rejected", "cancelled" ] }, "version": { "description": "Unchanged: a release writes nothing on the order.", "type": "integer" }, "released_reservations": { "description": "How many let go, 0 on a repeat.", "type": "integer" } }, "type": "object" }, "WebOrderReviewProblem": { "description": "A refusal. A non-null error_code names a controller refusal, and the data it carries sits beside the standard members. The permission middleware answers the same envelope with error_code null, and the tenant middleware answers only title, status and detail.", "required": [ "title", "status", "detail" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "error_code": { "type": "string", "nullable": true }, "errors": { "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "order_status": { "description": "With web_order_not_reviewable, web_order_already_decided and web_order_leftovers_not_releasable.", "type": "string" }, "current_version": { "description": "With web_order_version_conflict.", "type": "integer" }, "expected": { "description": "With payment_discrepancy: the frozen settle amount.", "allOf": [ { "$ref": "#/components/schemas/WebOrderMoney" } ] }, "observed": { "description": "With payment_discrepancy: the money the reviewer observed.", "allOf": [ { "$ref": "#/components/schemas/WebOrderMoney" } ] }, "client_id": { "description": "With client_fiscal_identity_incomplete.", "type": "string", "format": "uuid", "nullable": true }, "missing": { "description": "With client_fiscal_identity_incomplete: document, legal_name, fiscal_address, vat_taxpayer_type, islr_person_type; or client when the Client is unknown.", "type": "array", "items": { "type": "string" } } }, "type": "object" }, "WebOrderMiddlewareMessage": { "description": "What the auth middleware answers, and a path that matches no route.", "required": [ "message" ], "properties": { "message": { "type": "string" } }, "type": "object" }, "UsersAndRolesProblem": { "description": "Problem answered by the users, roles and role-permissions controllers. A 422 names each invalid field under errors.", "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string", "example": "The given data was invalid." }, "error_code": { "type": "string", "nullable": true }, "errors": { "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" }, "CompanyUser": { "description": "A user of the company. A list row and the record share this shape.", "required": [ "id", "name", "email", "role_id", "role_name", "created_at", "updated_at" ], "properties": { "subscription_disabled": { "type": "boolean" }, "id": { "type": "integer", "example": 41 }, "name": { "type": "string", "example": "Ana Pérez" }, "email": { "type": "string", "format": "email", "example": "ana@acme.com" }, "role_id": { "description": "The lowest-id role the user holds among this company's own roles; a role of another company never counts. Null, with role_name, when the user holds none.", "type": "integer", "example": 3, "nullable": true }, "role_name": { "type": "string", "example": "Contador", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "example": "2026-09-01T14:03:00+00:00", "nullable": true }, "updated_at": { "type": "string", "format": "date-time", "example": "2026-10-02T09:12:44+00:00", "nullable": true } }, "type": "object" }, "CompanyUserRoleCounts": { "description": "Members per role id of the company (every role, any status, zero-filled) plus none for members without a role. Counted under every filter except role_id; never crosses companies.", "required": [ "none" ], "properties": { "none": { "type": "integer", "minimum": 0 } }, "type": "object", "additionalProperties": { "type": "integer", "minimum": 0 } }, "CompanyUsersPage": { "required": [ "items", "total", "per_page", "current_page", "meta" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyUser" } }, "total": { "description": "Users matching every filter", "type": "integer", "minimum": 0 }, "per_page": { "type": "integer", "maximum": 100, "minimum": 1 }, "current_page": { "type": "integer", "minimum": 1 }, "meta": { "required": [ "counts" ], "properties": { "counts": { "$ref": "#/components/schemas/CompanyUserRoleCounts" } }, "type": "object" } }, "type": "object" }, "CreatedRecordId": { "description": "The id of the created user or role; read the record by it.", "required": [ "id" ], "properties": { "id": { "type": "integer", "example": 57 } }, "type": "object" }, "Role": { "description": "A role of the company. A list row and the record share this shape.", "required": [ "id", "code", "name", "description", "status", "creatorId", "updaterId", "companyId", "users_count", "is_super_admin" ], "properties": { "id": { "type": "integer", "example": 3 }, "code": { "type": "string", "example": "ROL00003" }, "name": { "type": "string", "example": "Contador" }, "description": { "type": "string", "example": "Contabilidad diaria", "nullable": true }, "status": { "description": "Published in lower case. Only the role update still accepts the deprecated upper-case spelling (ACTIVE, INACTIVE).", "type": "string", "example": "active", "enum": [ "active", "inactive" ] }, "creatorId": { "type": "integer", "example": 7 }, "updaterId": { "type": "integer", "example": 7 }, "companyId": { "type": "string", "format": "uuid" }, "users_count": { "description": "Members whose company role is this one", "type": "integer", "example": 51, "minimum": 0 }, "is_super_admin": { "description": "An administrator role holds every permission, so its permission matrix has no effect", "type": "boolean", "example": false } }, "type": "object" }, "RoleStatusCounts": { "description": "Roles per state under every filter except status", "required": [ "active", "inactive" ], "properties": { "active": { "type": "integer", "minimum": 0 }, "inactive": { "type": "integer", "minimum": 0 } }, "type": "object" }, "RolesPage": { "required": [ "items", "total", "per_page", "current_page", "meta" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Role" } }, "total": { "description": "Roles matching every filter", "type": "integer", "minimum": 0 }, "per_page": { "type": "integer", "maximum": 100, "minimum": 1 }, "current_page": { "type": "integer", "minimum": 1 }, "meta": { "required": [ "counts" ], "properties": { "counts": { "$ref": "#/components/schemas/RoleStatusCounts" } }, "type": "object" } }, "type": "object" }, "BankReconciliationAccountResource": { "description": "A treasury account as the bank reconciliation lists it: reconcilable when no other active treasury account of the company shares its accounting account and currency (ADR 0267), with how far its bank reconciliation has gone (ADR 0268).", "required": [ "id", "name", "kind", "bank_name", "currency", "status", "reconcilable", "conflicting_treasury_accounts", "start_month", "closed_through" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "example": "Banco VES" }, "kind": { "type": "string", "enum": [ "bank", "wallet", "cash", "credit_card" ] }, "bank_name": { "type": "string", "example": "Banco de prueba", "nullable": true }, "currency": { "type": "string", "example": "VES" }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "reconcilable": { "type": "boolean" }, "conflicting_treasury_accounts": { "description": "The other active accounts on the same accounting account and currency, ordered by name; empty when the account is reconcilable.", "type": "array", "items": { "required": [ "id", "name" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "example": "Banco VES (pagos)" } }, "type": "object" } }, "start_month": { "description": "The month the account's bank reconciliation starts (ADR 0268); null until it is started.", "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$", "example": "2026-09", "nullable": true }, "closed_through": { "description": "The latest closed month; every month from the start through it is closed. Null while none is, so always null while start_month is.", "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$", "example": "2026-09", "nullable": true } }, "type": "object" }, "BankReconciliationResource": { "description": "One month of a treasury account's bank reconciliation (ADR 0268). Its four figures and who closed it show only while it is closed, so a reopened month never shows the close it undid; who reopened it, when and why show whenever kept.", "required": [ "id", "treasury_account_id", "month", "currency", "status", "statement_closing_balance", "book_closing_balance", "outstanding_statement_total", "outstanding_book_total", "closed_at", "closed_by_user_id", "closed_by_api_key_id", "reopened_at", "reopened_by_user_id", "reopened_by_api_key_id", "reopen_reason" ], "properties": { "id": { "description": "The month's row; the document attachments hang from.", "type": "string", "format": "uuid" }, "treasury_account_id": { "type": "string", "format": "uuid" }, "month": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$", "example": "2026-09" }, "currency": { "type": "string", "example": "VES" }, "status": { "description": "Treat as an open set.", "type": "string", "enum": [ "open", "closed" ] }, "statement_closing_balance": { "description": "The closing balance the bank printed, entered at the close; null while open.", "type": "string", "example": "106600.00", "nullable": true }, "book_closing_balance": { "description": "The books' balance at the month's end when it closed; null while open.", "type": "string", "example": "106600.00", "nullable": true }, "outstanding_statement_total": { "description": "What the statement held outstanding at the close; null while open.", "type": "string", "example": "0.00", "nullable": true }, "outstanding_book_total": { "description": "What the books held outstanding at the close; null while open.", "type": "string", "example": "0.00", "nullable": true }, "closed_at": { "type": "string", "format": "date-time", "example": "2026-10-07T12:00:00+00:00", "nullable": true }, "closed_by_user_id": { "type": "string", "example": "42", "nullable": true }, "closed_by_api_key_id": { "type": "string", "nullable": true }, "reopened_at": { "type": "string", "format": "date-time", "nullable": true }, "reopened_by_user_id": { "type": "string", "nullable": true }, "reopened_by_api_key_id": { "type": "string", "nullable": true }, "reopen_reason": { "type": "string", "nullable": true, "maxLength": 500 } }, "type": "object" }, "BankReconciliationStartedResource": { "description": "An account's bank reconciliation, just started: the start month's row, open, and the opening statement line it created.", "required": [ "treasury_account_id", "start_month", "statement_opening_balance", "opening_statement_line_id", "reconciliation" ], "properties": { "treasury_account_id": { "type": "string", "format": "uuid" }, "start_month": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$", "example": "2026-09" }, "statement_opening_balance": { "description": "Signed, in the account's currency.", "type": "string", "example": "100000.00" }, "opening_statement_line_id": { "description": "The `opening` Bank Statement Line, dated the start month's first day.", "type": "string", "format": "uuid" }, "reconciliation": { "$ref": "#/components/schemas/BankReconciliationResource" } }, "type": "object" }, "BankReconciliationStartCorrectedResource": { "description": "An account's bank reconciliation start, just corrected (ADR 0305): the start as after a start, plus the correction's id.", "required": [ "treasury_account_id", "start_month", "statement_opening_balance", "opening_statement_line_id", "reconciliation", "correction_id" ], "properties": { "treasury_account_id": { "type": "string", "format": "uuid" }, "start_month": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$", "example": "2026-09" }, "statement_opening_balance": { "description": "Signed, in the account's currency.", "type": "string", "example": "1250.00" }, "opening_statement_line_id": { "description": "The `opening` Bank Statement Line, dated the corrected start month's first day; same id as before.", "type": "string", "format": "uuid" }, "reconciliation": { "$ref": "#/components/schemas/BankReconciliationResource" }, "correction_id": { "description": "The append-only correction record.", "type": "string", "format": "uuid" } }, "type": "object" }, "BankReconciliationProofStatementLineResource": { "description": "A Bank Statement Line outstanding at the month's end, with its note.", "required": [ "id", "kind", "operation_date", "value_date", "reference", "description", "amount", "note", "noted_at", "noted_by_user_id", "noted_by_api_key_id", "match_id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "kind": { "description": "Treat as an open set.", "type": "string", "enum": [ "movement", "opening" ] }, "operation_date": { "type": "string", "format": "date", "example": "2026-09-25" }, "value_date": { "type": "string", "format": "date", "nullable": true }, "reference": { "type": "string", "example": "B13", "nullable": true }, "description": { "type": "string", "example": "Abono no identificado", "nullable": true }, "amount": { "description": "Signed: positive is money in, in the account's currency.", "type": "string", "example": "750.00" }, "note": { "type": "string", "example": "Depósito sin identificar", "nullable": true, "maxLength": 500 }, "noted_at": { "type": "string", "format": "date-time", "nullable": true }, "noted_by_user_id": { "type": "string", "example": "42", "nullable": true }, "noted_by_api_key_id": { "type": "string", "nullable": true }, "match_id": { "description": "The active match holding the line, which reaches into a later month so it reconciles the line only then; null when no match holds it.", "type": "string", "format": "uuid", "nullable": true } }, "type": "object" }, "BankReconciliationProofLedgerLineResource": { "description": "A ledger line on the account's key outstanding at the month's end, with its entry and the document it posted.", "required": [ "id", "date", "amount", "transaction_id", "transaction_code", "transaction_type", "linkable_type", "linkable_id", "document_code", "reference", "description", "match_id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "date": { "type": "string", "format": "date", "example": "2026-09-30" }, "amount": { "description": "Signed: positive is money in, in the account's currency.", "type": "string", "example": "2000.00" }, "transaction_id": { "type": "string", "format": "uuid" }, "transaction_code": { "type": "string", "example": "AS-000123" }, "transaction_type": { "type": "string", "example": "sales_collection.applied" }, "linkable_type": { "description": "Treat as an open set.", "type": "string", "example": "sales_collection" }, "linkable_id": { "type": "string", "format": "uuid" }, "document_code": { "type": "string", "example": "COB-000045", "nullable": true }, "reference": { "type": "string", "example": "COBRO", "nullable": true }, "description": { "type": "string", "nullable": true }, "match_id": { "description": "The active match holding the line, which reaches into a later month so it reconciles the line only then; null when no match holds it.", "type": "string", "format": "uuid", "nullable": true } }, "type": "object" }, "BankReconciliationProofResource": { "description": "A month's bank reconciliation proof (ADR 0268), computed on every read, with the month's row when it has one and what a client needs to offer its close or reopening.", "required": [ "treasury_account_id", "currency", "month", "month_end", "start_month", "status", "reconciliation", "statement_balance", "book_balance", "statement_outstanding", "book_outstanding", "pre_start_balance", "statement_outstanding_total", "book_outstanding_total", "difference", "balanced", "month_ended", "previous_month_closed", "is_latest_closed" ], "properties": { "treasury_account_id": { "type": "string", "format": "uuid" }, "currency": { "type": "string", "example": "VES" }, "month": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$", "example": "2026-09" }, "month_end": { "type": "string", "format": "date", "example": "2026-09-30" }, "start_month": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$", "example": "2026-09" }, "status": { "description": "The month's row's status; open while it has none. Treat as an open set.", "type": "string", "enum": [ "open", "closed" ] }, "reconciliation": { "description": "The month's row, as BankReconciliationResource; null while it has none. A closed row keeps the figures its close stored.", "required": [ "id", "treasury_account_id", "month", "currency", "status", "statement_closing_balance", "book_closing_balance", "outstanding_statement_total", "outstanding_book_total", "closed_at", "closed_by_user_id", "closed_by_api_key_id", "reopened_at", "reopened_by_user_id", "reopened_by_api_key_id", "reopen_reason" ], "properties": { "id": { "type": "string", "format": "uuid" }, "treasury_account_id": { "type": "string", "format": "uuid" }, "month": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$", "example": "2026-09" }, "currency": { "type": "string", "example": "VES" }, "status": { "description": "Treat as an open set.", "type": "string", "enum": [ "open", "closed" ] }, "statement_closing_balance": { "type": "string", "example": "106600.00", "nullable": true }, "book_closing_balance": { "type": "string", "example": "106600.00", "nullable": true }, "outstanding_statement_total": { "type": "string", "example": "0.00", "nullable": true }, "outstanding_book_total": { "type": "string", "example": "0.00", "nullable": true }, "closed_at": { "type": "string", "format": "date-time", "nullable": true }, "closed_by_user_id": { "type": "string", "nullable": true }, "closed_by_api_key_id": { "type": "string", "nullable": true }, "reopened_at": { "type": "string", "format": "date-time", "nullable": true }, "reopened_by_user_id": { "type": "string", "nullable": true }, "reopened_by_api_key_id": { "type": "string", "nullable": true }, "reopen_reason": { "type": "string", "nullable": true, "maxLength": 500 } }, "type": "object", "nullable": true }, "statement_balance": { "description": "The account's statement lines dated from the start month's first day through the month's end, the opening line included.", "type": "string", "example": "106600.00" }, "book_balance": { "description": "The books' balance of the account's key at the month's end.", "type": "string", "example": "108600.00" }, "statement_outstanding": { "description": "By day, then id; at most 2000.", "type": "array", "items": { "$ref": "#/components/schemas/BankReconciliationProofStatementLineResource" } }, "book_outstanding": { "description": "By day, then entry code, then id; at most 2000. Never holds the balance before the start.", "type": "array", "items": { "$ref": "#/components/schemas/BankReconciliationProofLedgerLineResource" } }, "pre_start_balance": { "description": "The books' balance before the start: outstanding while no match reconciles it at the month's end and it is not zero, then counted in book_outstanding_total.", "required": [ "date", "amount", "outstanding", "match_id", "matched_amount" ], "properties": { "date": { "type": "string", "format": "date", "example": "2026-08-31" }, "amount": { "description": "The balance as it stands now.", "type": "string", "example": "0.00" }, "outstanding": { "type": "boolean" }, "match_id": { "type": "string", "format": "uuid", "nullable": true }, "matched_amount": { "description": "The balance the match holding it took when matched; differs from amount when a line dated before the start was posted since.", "type": "string", "nullable": true } }, "type": "object" }, "statement_outstanding_total": { "type": "string", "example": "0.00" }, "book_outstanding_total": { "type": "string", "example": "2000.00" }, "difference": { "description": "(statement_balance − statement_outstanding_total) − (book_balance − book_outstanding_total).", "type": "string", "example": "0.00" }, "balanced": { "description": "Whether the difference is 0.00.", "type": "boolean" }, "month_ended": { "description": "Whether the month has ended in the company's time zone.", "type": "boolean" }, "previous_month_closed": { "description": "True for the start month; otherwise whether the month before is closed.", "type": "boolean" }, "is_latest_closed": { "description": "Whether this is the closed-through month, the only one that reopens.", "type": "boolean" } }, "type": "object" }, "BankReconciliationProofTooManyLinesProblem": { "description": "A side holds more outstanding lines at the month's end than a proof lists; matching some of them first answers.", "required": [ "title", "status", "detail", "error_code", "errors", "side", "limit" ], "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string" }, "error_code": { "type": "string", "enum": [ "bank_reconciliation_proof_too_many_lines" ] }, "errors": { "description": "Always null.", "type": "object", "nullable": true }, "side": { "type": "string", "enum": [ "statement", "ledger" ] }, "limit": { "type": "integer", "example": 2000 } }, "type": "object" }, "BankReconciliationMonthStateProblem": { "description": "The month is in the wrong state for the request: already closed (409), or closed but not the closed-through month (422); closed_through names the latest closed month.", "required": [ "title", "status", "detail", "error_code", "errors", "month", "closed_through" ], "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "detail": { "type": "string" }, "error_code": { "type": "string", "enum": [ "bank_reconciliation_already_closed", "bank_reconciliation_not_latest_closed" ] }, "errors": { "description": "Always null.", "type": "object", "nullable": true }, "month": { "type": "string", "example": "2026-09" }, "closed_through": { "type": "string", "example": "2026-09" } }, "type": "object" }, "BankReconciliationOutOfOrderProblem": { "description": "The month before is not closed and this is not the start month; expected_month is the month to close first.", "required": [ "title", "status", "detail", "error_code", "errors", "month", "expected_month" ], "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string" }, "error_code": { "type": "string", "enum": [ "bank_reconciliation_out_of_order" ] }, "errors": { "description": "Always null.", "type": "object", "nullable": true }, "month": { "type": "string", "example": "2026-11" }, "expected_month": { "type": "string", "example": "2026-10" } }, "type": "object" }, "BankReconciliationMonthProblem": { "description": "The month has not ended in the company's time zone (close), or is open (reopen).", "required": [ "title", "status", "detail", "error_code", "errors", "month" ], "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string" }, "error_code": { "type": "string", "enum": [ "bank_reconciliation_month_not_ended", "bank_reconciliation_not_closed" ] }, "errors": { "description": "Always null.", "type": "object", "nullable": true }, "month": { "type": "string", "example": "2026-10" } }, "type": "object" }, "StatementLinesIncompleteProblem": { "description": "The closing balance the bank printed is not the sum of the statement lines through the month's end.", "required": [ "title", "status", "detail", "error_code", "errors", "currency", "statement_closing_balance", "statement_balance", "difference" ], "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string" }, "error_code": { "type": "string", "enum": [ "statement_lines_incomplete" ] }, "errors": { "description": "Always null.", "type": "object", "nullable": true }, "currency": { "type": "string", "example": "VES" }, "statement_closing_balance": { "description": "The balance entered.", "type": "string", "example": "106000.00" }, "statement_balance": { "description": "The statement lines' sum.", "type": "string", "example": "106600.00" }, "difference": { "description": "statement_closing_balance − statement_balance.", "type": "string", "example": "-600.00" } }, "type": "object" }, "BankReconciliationUnbalancedProblem": { "description": "The month's proof leaves a difference nobody explained.", "required": [ "title", "status", "detail", "error_code", "errors", "currency", "statement_balance", "statement_outstanding_total", "book_balance", "book_outstanding_total", "difference" ], "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string" }, "error_code": { "type": "string", "enum": [ "bank_reconciliation_unbalanced" ] }, "errors": { "description": "Always null.", "type": "object", "nullable": true }, "currency": { "type": "string", "example": "VES" }, "statement_balance": { "type": "string", "example": "100000.00" }, "statement_outstanding_total": { "type": "string", "example": "0.00" }, "book_balance": { "type": "string", "example": "100500.00" }, "book_outstanding_total": { "type": "string", "example": "0.00" }, "difference": { "type": "string", "example": "-500.00" } }, "type": "object" }, "BankReconciliationMonthClosedProblem": { "description": "Every line the match holds, or would hold, is dated on or before the closed-through month's last day, so it can be neither made nor undone until that month reopens.", "required": [ "title", "status", "detail", "error_code", "errors", "closed_through" ], "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "detail": { "type": "string" }, "error_code": { "type": "string", "enum": [ "bank_reconciliation_month_closed" ] }, "errors": { "description": "Always null.", "type": "object", "nullable": true }, "closed_through": { "type": "string", "example": "2026-09" } }, "type": "object" }, "BankStatementImportMonthClosedProblem": { "description": "A row that would be new is dated in a bank reconciliation month closed since the draft was uploaded; upload it again.", "required": [ "title", "status", "detail", "error_code", "errors", "frozen_through" ], "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "detail": { "type": "string" }, "error_code": { "type": "string", "enum": [ "bank_statement_import_month_closed" ] }, "errors": { "description": "Always null.", "type": "object", "nullable": true }, "frozen_through": { "description": "The closed-through month's last day.", "type": "string", "format": "date", "example": "2026-09-30" } }, "type": "object" }, "BankReconciliationNotStartedProblem": { "description": "The account's bank reconciliation has not started (start_month null), or starts after the month asked for (start_month names it).", "required": [ "title", "status", "detail", "error_code", "errors", "start_month" ], "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string" }, "error_code": { "type": "string", "enum": [ "bank_reconciliation_not_started" ] }, "errors": { "description": "Always null.", "type": "object", "nullable": true }, "start_month": { "type": "string", "example": "2026-09", "nullable": true } }, "type": "object" }, "BankReconciliationMatchCrossesStartProblem": { "description": "The match would hold lines dated both before and from the month the bank reconciliation starts.", "required": [ "title", "status", "detail", "error_code", "errors", "start_month" ], "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string" }, "error_code": { "type": "string", "enum": [ "bank_reconciliation_match_crosses_start" ] }, "errors": { "description": "Always null.", "type": "object", "nullable": true }, "start_month": { "type": "string", "example": "2026-09" } }, "type": "object" }, "BankReconciliationAlreadyStartedProblem": { "description": "The account's bank reconciliation already started; a client retrying its own start finds its start month.", "required": [ "title", "status", "detail", "error_code", "errors", "start_month" ], "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "detail": { "type": "string" }, "error_code": { "type": "string", "enum": [ "bank_reconciliation_already_started" ] }, "errors": { "description": "Always null.", "type": "object", "nullable": true }, "start_month": { "type": "string", "example": "2026-09" } }, "type": "object" }, "BankReconciliationStartMonthInFutureProblem": { "description": "The start month comes after the company's current month.", "required": [ "title", "status", "detail", "error_code", "errors", "current_month" ], "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string" }, "error_code": { "type": "string", "enum": [ "bank_reconciliation_start_month_in_future" ] }, "errors": { "description": "Always null.", "type": "object", "nullable": true }, "current_month": { "description": "The company's current month, in its time zone.", "type": "string", "example": "2026-10" } }, "type": "object" }, "BankReconciliationStartSplitsMatchesProblem": { "description": "Active matches hold lines dated both before and from the start month; undo them first.", "required": [ "title", "status", "detail", "error_code", "errors", "match_ids" ], "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "detail": { "type": "string" }, "error_code": { "type": "string", "enum": [ "bank_reconciliation_start_splits_matches" ] }, "errors": { "description": "Always null.", "type": "object", "nullable": true }, "match_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } } }, "type": "object" }, "BankReconciliationHasClosedMonthsProblem": { "description": "The start cannot be corrected while any month is closed; reopen the closed-through month first.", "required": [ "title", "status", "detail", "error_code", "errors", "closed_through" ], "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "detail": { "type": "string" }, "error_code": { "type": "string", "enum": [ "bank_reconciliation_has_closed_months" ] }, "errors": { "description": "Always null.", "type": "object", "nullable": true }, "closed_through": { "type": "string", "example": "2026-09" } }, "type": "object" }, "BankReconciliationOpeningLineMatchedProblem": { "description": "The opening statement line is in an active match; undo the matches first.", "required": [ "title", "status", "detail", "error_code", "errors", "match_ids" ], "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "detail": { "type": "string" }, "error_code": { "type": "string", "enum": [ "bank_reconciliation_opening_line_matched" ] }, "errors": { "description": "Always null.", "type": "object", "nullable": true }, "match_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } } }, "type": "object" }, "BankReconciliationStartUnchangedProblem": { "description": "The correction must change the start month or the statement opening balance.", "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string" }, "error_code": { "type": "string", "enum": [ "bank_reconciliation_start_unchanged" ] }, "errors": { "description": "Always null.", "type": "object", "nullable": true } }, "type": "object" }, "InvalidBankReconciliationStartCorrectionReasonProblem": { "description": "The correction reason is empty or longer than 500 characters after Unicode trim.", "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string" }, "error_code": { "type": "string", "enum": [ "invalid_bank_reconciliation_start_correction_reason" ] }, "errors": { "description": "Always null.", "type": "object", "nullable": true } }, "type": "object" }, "BankStatementImportProfileResource": { "description": "A Bank Statement Import Profile: one bank's CSV or Excel layout, its columns named by spreadsheet letter (A–ZZ) or by the title in the file's header row.", "required": [ "id", "name", "format", "columns_by", "header_row", "delimiter", "date_format", "number_format", "amount_mode", "columns", "created_at", "updated_at" ], "properties": { "id": { "description": "Shared by the bank statement import profile, import and line endpoints\n(MER-3848).", "type": "string", "format": "uuid" }, "name": { "type": "string", "example": "Banco VES (CSV)" }, "format": { "type": "string", "enum": [ "csv", "xlsx" ] }, "columns_by": { "description": "Whether `columns` holds spreadsheet letters or header titles.", "type": "string", "enum": [ "letter", "header" ] }, "header_row": { "description": "The 1-based row holding the column titles; 0 when the file has none. Data starts on the next row.", "type": "integer", "example": 3, "maximum": 100, "minimum": 0 }, "delimiter": { "description": "Set for csv, null for xlsx.", "type": "string", "nullable": true, "enum": [ "comma", "semicolon", "tab", "pipe" ] }, "date_format": { "type": "string", "enum": [ "d/m/Y", "d-m-Y", "d.m.Y", "Y-m-d", "Y/m/d", "m/d/Y", "d/m/y" ] }, "number_format": { "description": "es_VE reads 1.234,56; en reads 1,234.56.", "type": "string", "enum": [ "es_VE", "en" ] }, "amount_mode": { "type": "string", "enum": [ "signed", "debit_credit" ] }, "columns": { "description": "The spreadsheet letter or the header title of each field's column; null when unmapped.", "required": [ "operation_date", "value_date", "reference", "description", "amount", "debit", "credit", "balance" ], "properties": { "operation_date": { "type": "string", "example": "A" }, "value_date": { "type": "string", "nullable": true }, "reference": { "type": "string", "example": "B", "nullable": true }, "description": { "type": "string", "example": "C" }, "amount": { "description": "Mapped only in signed mode.", "type": "string", "nullable": true }, "debit": { "description": "Money out; mapped only in debit_credit mode.", "type": "string", "example": "D", "nullable": true }, "credit": { "description": "Money in; mapped only in debit_credit mode.", "type": "string", "example": "E", "nullable": true }, "balance": { "type": "string", "example": "F", "nullable": true } }, "type": "object" }, "created_at": { "type": "string", "format": "date-time", "example": "2026-10-10T20:00:00+00:00" }, "updated_at": { "type": "string", "format": "date-time", "example": "2026-10-10T20:00:00+00:00" } }, "type": "object" }, "BankStatementProblem": { "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string" }, "error_code": { "description": "Null for a plain validation error or a permission refusal.", "type": "string", "nullable": true }, "errors": { "description": "The failing fields of a validation error; null otherwise.", "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" }, "BankStatementMiddlewareProblem": { "required": [ "title", "status", "detail" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "reason": { "description": "Present when tenant role membership is refused", "type": "string" } }, "type": "object" }, "BankStatementMessageError": { "required": [ "message" ], "properties": { "message": { "type": "string" }, "status": { "type": "string", "enum": [ "email_not_verified" ] }, "detail": { "type": "string" } }, "type": "object" }, "BankStatementImportResource": { "description": "A bank statement import: a draft read from one file with one profile for one treasury account, then confirmed once or discarded. The file is stored as evidence and is not served. Counts and days come from the draft and, once confirmed, from the confirm-time duplicate check, where a `new` row is one that became a line.", "required": [ "id", "treasury_account_id", "profile_id", "profile_name", "currency", "format", "source_file_name", "status", "rows_count", "new_count", "duplicate_count", "error_count", "imported_count", "first_operation_date", "last_operation_date", "mapped_headers", "uploaded_at", "uploaded_by_user_id", "uploaded_by_api_key_id", "confirmed_at", "confirmed_by_user_id", "confirmed_by_api_key_id", "discarded_at", "discarded_by_user_id", "discarded_by_api_key_id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "treasury_account_id": { "type": "string", "format": "uuid" }, "profile_id": { "description": "The profile it was read with; it may have been deleted since.", "type": "string", "format": "uuid" }, "profile_name": { "description": "The profile's name when the file was read.", "type": "string", "example": "Banco VES (CSV)" }, "currency": { "description": "The treasury account's currency when the file was read; every amount is in it.", "type": "string", "enum": [ "USD", "VES", "USDT", "EUR", "DOP" ] }, "format": { "type": "string", "enum": [ "csv", "xlsx" ] }, "source_file_name": { "type": "string", "example": "septiembre.csv" }, "status": { "type": "string", "enum": [ "draft", "confirmed", "discarded" ] }, "rows_count": { "description": "The non-blank data rows of the file.", "type": "integer", "example": 13, "minimum": 1 }, "new_count": { "type": "integer", "example": 13, "minimum": 0 }, "duplicate_count": { "type": "integer", "example": 0, "minimum": 0 }, "error_count": { "type": "integer", "example": 0, "minimum": 0 }, "imported_count": { "description": "The lines the confirm created; null until confirmed.", "type": "integer", "nullable": true, "minimum": 1 }, "first_operation_date": { "description": "The earliest operation day among the new rows.", "type": "string", "format": "date", "example": "2026-09-03", "nullable": true }, "last_operation_date": { "description": "The latest operation day among the new rows.", "type": "string", "format": "date", "example": "2026-09-25", "nullable": true }, "mapped_headers": { "description": "The title the file prints above each mapped column, to check the mapping; null for an unmapped field, a blank title or a profile without a header row.", "required": [ "operation_date", "value_date", "reference", "description", "amount", "debit", "credit", "balance" ], "properties": { "operation_date": { "type": "string", "example": "Fecha", "nullable": true }, "value_date": { "type": "string", "nullable": true }, "reference": { "type": "string", "example": "Referencia", "nullable": true }, "description": { "type": "string", "example": "Concepto", "nullable": true }, "amount": { "type": "string", "nullable": true }, "debit": { "type": "string", "example": "Débito", "nullable": true }, "credit": { "type": "string", "example": "Crédito", "nullable": true }, "balance": { "type": "string", "example": "Saldo", "nullable": true } }, "type": "object" }, "uploaded_at": { "type": "string", "format": "date-time", "example": "2026-10-10T20:00:00+00:00" }, "uploaded_by_user_id": { "type": "string", "example": "42", "nullable": true }, "uploaded_by_api_key_id": { "type": "string", "nullable": true }, "confirmed_at": { "type": "string", "format": "date-time", "nullable": true }, "confirmed_by_user_id": { "type": "string", "nullable": true }, "confirmed_by_api_key_id": { "type": "string", "nullable": true }, "discarded_at": { "type": "string", "format": "date-time", "nullable": true }, "discarded_by_user_id": { "type": "string", "nullable": true }, "discarded_by_api_key_id": { "type": "string", "nullable": true } }, "type": "object" }, "BankStatementImportRowResource": { "description": "One data row of an import as read with its profile. An error row carries its code and detail and no parsed field.", "required": [ "row_number", "status", "error_code", "error_detail", "operation_date", "value_date", "reference", "description", "signed_amount", "balance", "source" ], "properties": { "row_number": { "description": "The row of the file (the record number of a CSV).", "type": "integer", "example": 4, "minimum": 1 }, "status": { "type": "string", "enum": [ "new", "duplicate", "error" ] }, "error_code": { "description": "Set only for an error row. `closed_month`: the row would be new and is dated in a closed bank reconciliation month; its cells are kept. Treat as an open set.", "type": "string", "nullable": true, "enum": [ "invalid_date", "invalid_amount", "missing_column", "closed_month", null ] }, "error_detail": { "description": "The precise reason of an error row, under its error_code. Treat as an open set.", "type": "string", "nullable": true, "enum": [ "missing_operation_date", "invalid_operation_date", "invalid_value_date", "missing_description", "missing_amount", "invalid_amount", "amount_precision_exceeded", "amount_out_of_range", "zero_amount", "both_debit_and_credit", "invalid_balance", "dated_in_closed_month", null ] }, "operation_date": { "type": "string", "format": "date", "example": "2026-09-03", "nullable": true }, "value_date": { "type": "string", "format": "date", "nullable": true }, "reference": { "type": "string", "example": "B01", "nullable": true }, "description": { "type": "string", "example": "Abono transferencia", "nullable": true }, "signed_amount": { "description": "Positive is money in, in the import's currency.", "type": "string", "example": "6600.00", "nullable": true }, "balance": { "type": "string", "example": "106600.00", "nullable": true }, "source": { "description": "The text of each field's cell as the bank wrote it: null when the field is unmapped, empty when its cell is blank.", "required": [ "operation_date", "value_date", "reference", "description", "amount", "debit", "credit", "balance" ], "properties": { "operation_date": { "type": "string", "example": "03/09/2026", "nullable": true }, "value_date": { "type": "string", "nullable": true }, "reference": { "type": "string", "example": "B01", "nullable": true }, "description": { "type": "string", "example": "Abono transferencia", "nullable": true }, "amount": { "type": "string", "nullable": true }, "debit": { "type": "string", "example": "", "nullable": true }, "credit": { "type": "string", "example": "6.600,00", "nullable": true }, "balance": { "type": "string", "example": "106.600,00", "nullable": true } }, "type": "object" } }, "type": "object" }, "TreasuryAccountNotReconcilableProblem": { "description": "The treasury account shares its accounting account and currency with other active accounts of the company (ADR 0267).", "required": [ "title", "status", "detail", "error_code", "errors", "conflicting_treasury_accounts" ], "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string" }, "error_code": { "type": "string", "enum": [ "treasury_account_not_reconcilable" ] }, "errors": { "description": "Always null.", "type": "object", "nullable": true }, "conflicting_treasury_accounts": { "description": "The other active accounts on the same accounting account and currency, ordered by name.", "type": "array", "items": { "required": [ "id", "name" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "example": "Banco USD" } }, "type": "object" } } }, "type": "object" }, "BankStatementHeaderNotFoundProblem": { "description": "A profile that finds its columns by title refuses a file whose header row lacks one or more of those titles (MER-4655).", "required": [ "title", "status", "detail", "error_code", "errors", "missing_headers" ], "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string", "example": "La fila de encabezado del archivo no tiene ninguna columna titulada Débito, Saldo" }, "error_code": { "type": "string", "enum": [ "bank_statement_header_not_found" ] }, "errors": { "description": "Always null.", "type": "object", "nullable": true }, "missing_headers": { "description": "The profile's titles the file's header row lacks, in the profile's spelling.", "type": "array", "items": { "type": "string", "example": "Débito" }, "example": [ "Débito", "Saldo" ] } }, "type": "object" }, "BankStatementLineResource": { "description": "A Bank Statement Line: one movement of an imported statement for a treasury account. Its movement is never edited; only its note.", "required": [ "id", "treasury_account_id", "import_id", "import_row_number", "kind", "operation_date", "value_date", "reference", "description", "signed_amount", "balance", "created_at", "created_by_user_id", "created_by_api_key_id", "note", "noted_at", "noted_by_user_id", "noted_by_api_key_id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "treasury_account_id": { "type": "string", "format": "uuid" }, "import_id": { "description": "The import it came from; null for an opening line.", "type": "string", "format": "uuid", "nullable": true }, "import_row_number": { "description": "Its row in the imported file; null for an opening line.", "type": "integer", "example": 4, "nullable": true }, "kind": { "description": "`opening` carries a statement's opening balance and is created by an account's first reconciliation, never by an import.", "type": "string", "enum": [ "movement", "opening" ] }, "operation_date": { "type": "string", "format": "date", "example": "2026-09-03" }, "value_date": { "type": "string", "format": "date", "nullable": true }, "reference": { "type": "string", "example": "B01", "nullable": true }, "description": { "type": "string", "example": "Abono transferencia", "nullable": true }, "signed_amount": { "description": "Positive is money in, in the account's currency.", "type": "string", "example": "6600.00" }, "balance": { "type": "string", "example": "106600.00", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "example": "2026-10-10T20:00:00+00:00" }, "created_by_user_id": { "type": "string", "example": "42", "nullable": true }, "created_by_api_key_id": { "type": "string", "nullable": true }, "note": { "description": "What a user wrote about the line, such as an unidentified credit; it never changes the match state. The four note fields are null together.", "type": "string", "example": "Depósito sin identificar", "nullable": true, "maxLength": 500 }, "noted_at": { "type": "string", "format": "date-time", "example": "2026-10-11T15:00:00+00:00", "nullable": true }, "noted_by_user_id": { "type": "string", "example": "42", "nullable": true }, "noted_by_api_key_id": { "type": "string", "nullable": true } }, "type": "object" }, "CashMovementCounterpart": { "description": "A treasury account a Movimiento de caja of the Caja may use as its counterpart.", "required": [ "id", "name", "kind", "currency" ], "properties": { "id": { "description": "The treasury account's id, which a movement takes as counterpart_treasury_account_id.", "type": "string", "format": "uuid" }, "name": { "type": "string", "example": "Banco USD" }, "kind": { "type": "string", "enum": [ "bank", "wallet", "cash", "credit_card" ] }, "currency": { "type": "string", "example": "USD" } }, "type": "object" }, "CashMovementCounterpartList": { "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CashMovementCounterpart" } } }, "type": "object" }, "CashMovementCounterpartProblem": { "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "error_code": { "type": "string", "nullable": true }, "errors": { "description": "Request validation messages by field.", "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" }, "CashCountExpectedBreakdown": { "description": "The expected cash of one currency explained from the ledger (ADR 0378-an-arqueo-breaks-its-expected-cash-down-from-the-ledger-after-its-turnos-cut). The figures are signed, money in positive and money out negative, and their eight lines add up to the line's expected amount. The lines are gross by ledger type: a sale voided in its own Turno reads in collections and in collection_reversals, which net to what its method shows as applied.", "required": [ "opening", "collections", "collection_reversals", "refunds", "cash_movements", "payments", "count_differences", "other" ], "properties": { "opening": { "description": "The Turno's opening expected amount.", "type": "string", "example": "20.00" }, "collections": { "description": "Collections and customer advances received into the drawer after the cut.", "type": "string", "example": "19.95" }, "collection_reversals": { "description": "Collections and customer advances cancelled after the cut, whichever Turno received them.", "type": "string", "example": "-3.75" }, "refunds": { "description": "Credit Balance Refunds, and their cancellations, after the cut.", "type": "string", "example": "-2.90" }, "cash_movements": { "description": "Treasury Transfers through the drawer, and their cancellations, after the cut.", "type": "string", "example": "0.00" }, "payments": { "description": "Purchase payments and supplier advances, and their cancellations, after the cut.", "type": "string", "example": "0.00" }, "count_differences": { "description": "Differences of earlier Arqueos posted after the cut.", "type": "string", "example": "0.00" }, "other": { "description": "The balancing figure: the expected amount less the other seven lines. A ledger type none of them names reads here.", "type": "string", "example": "0.00" } }, "type": "object" }, "ReconciliationMatchLineResource": { "description": "A line a match holds, with the day and the signed amount it had when matched.", "required": [ "id", "date", "amount" ], "properties": { "id": { "type": "string", "format": "uuid" }, "date": { "type": "string", "format": "date", "example": "2026-09-05" }, "amount": { "description": "Signed: positive is money in, in the account's currency.", "type": "string", "example": "9000.00" } }, "type": "object" }, "ReconciliationMatchResource": { "description": "A Reconciliation Match: Bank Statement Lines of a treasury account matched with ledger lines of its accounting account and currency, both sides summing exactly; the book side may also hold the books' balance before the account's bank reconciliation starts. An undone match keeps its lines with who undid it and when.", "required": [ "id", "treasury_account_id", "currency", "status", "amount", "statement_lines", "ledger_lines", "pre_start_balance", "matched_at", "matched_by_user_id", "matched_by_api_key_id", "undone_at", "undone_by_user_id", "undone_by_api_key_id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "treasury_account_id": { "type": "string", "format": "uuid" }, "currency": { "type": "string", "example": "VES" }, "status": { "description": "Treat as an open set.", "type": "string", "enum": [ "active", "undone" ] }, "amount": { "description": "What each side sums to; 0.00 for a pair that cancels out, such as a collection and its reversal.", "type": "string", "example": "9000.00" }, "statement_lines": { "description": "Ordered by day, then id; empty for a ledger pair that cancels out.", "type": "array", "items": { "$ref": "#/components/schemas/ReconciliationMatchLineResource" } }, "ledger_lines": { "description": "Ordered by day, then id; empty for a statement pair that cancels out. Never holds the balance before the start.", "type": "array", "items": { "$ref": "#/components/schemas/ReconciliationMatchLineResource" } }, "pre_start_balance": { "description": "The books' balance before the account's bank reconciliation starts, when the match holds it: dated the day before the start month, with the amount it had when matched. Null otherwise.", "required": [ "date", "amount" ], "properties": { "date": { "type": "string", "format": "date", "example": "2026-08-31" }, "amount": { "description": "Signed, in the account's currency.", "type": "string", "example": "100000.00" } }, "type": "object", "nullable": true }, "matched_at": { "type": "string", "format": "date-time", "example": "2026-10-11T14:00:00+00:00" }, "matched_by_user_id": { "type": "string", "example": "42", "nullable": true }, "matched_by_api_key_id": { "type": "string", "nullable": true }, "undone_at": { "type": "string", "format": "date-time", "nullable": true }, "undone_by_user_id": { "type": "string", "nullable": true }, "undone_by_api_key_id": { "type": "string", "nullable": true } }, "type": "object" }, "ReconciliationStatementLineResource": { "description": "A Bank Statement Line of the workspace with its match state and its note.", "required": [ "id", "kind", "operation_date", "value_date", "reference", "description", "amount", "balance", "import_id", "match_id", "state", "note", "noted_at", "noted_by_user_id", "noted_by_api_key_id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "kind": { "description": "Treat as an open set.", "type": "string", "enum": [ "movement", "opening" ] }, "operation_date": { "type": "string", "format": "date", "example": "2026-09-05" }, "value_date": { "type": "string", "format": "date", "nullable": true }, "reference": { "type": "string", "example": "B01", "nullable": true }, "description": { "type": "string", "example": "Abono transferencia", "nullable": true }, "amount": { "description": "Signed: positive is money in, in the account's currency.", "type": "string", "example": "9000.00" }, "balance": { "type": "string", "example": "109000.00", "nullable": true }, "import_id": { "type": "string", "format": "uuid", "nullable": true }, "match_id": { "description": "The active match that holds the line; null exactly when the line is in transit.", "type": "string", "format": "uuid", "nullable": true }, "state": { "description": "Treat as an open set.", "type": "string", "enum": [ "matched", "in_transit" ] }, "note": { "description": "What a user wrote about the line, such as an unidentified credit; it never changes the state. The four note fields are null together.", "type": "string", "example": "Depósito sin identificar", "nullable": true, "maxLength": 500 }, "noted_at": { "type": "string", "format": "date-time", "example": "2026-10-11T15:00:00+00:00", "nullable": true }, "noted_by_user_id": { "type": "string", "example": "42", "nullable": true }, "noted_by_api_key_id": { "type": "string", "nullable": true } }, "type": "object" }, "ReconciliationLedgerLineResource": { "description": "A ledger line on the treasury account's accounting account and currency, with its entry, the document it posted and its match state.", "required": [ "id", "date", "amount", "transaction_id", "transaction_code", "transaction_type", "linkable_type", "linkable_id", "document_code", "reference", "description", "reverses_transaction_id", "match_id", "state" ], "properties": { "id": { "type": "string", "format": "uuid" }, "date": { "type": "string", "format": "date", "example": "2026-09-04" }, "amount": { "description": "Signed: positive is money in, in the account's currency.", "type": "string", "example": "3000.00" }, "transaction_id": { "type": "string", "format": "uuid" }, "transaction_code": { "type": "string", "example": "AS-000123" }, "transaction_type": { "type": "string", "example": "sales_collection.applied" }, "linkable_type": { "description": "The kind of document the entry posted, such as sales_collection, purchase_payment, treasury_transfer, withholding_remittance, manual_entry or opening_balance. Treat as an open set.", "type": "string", "example": "sales_collection" }, "linkable_id": { "type": "string", "format": "uuid" }, "document_code": { "type": "string", "example": "COB-000045", "nullable": true }, "reference": { "description": "The bank reference: for a collection or payment, the references of its method lines posting to this account, joined by ', '; a transfer's reference; a remittance's bank reference; a manual entry's source reference.", "type": "string", "example": "B01", "nullable": true }, "description": { "type": "string", "nullable": true }, "reverses_transaction_id": { "description": "The entry this line's entry reverses, for a cancellation.", "type": "string", "format": "uuid", "nullable": true }, "match_id": { "description": "The active match that holds the line; null exactly when the line is in transit.", "type": "string", "format": "uuid", "nullable": true }, "state": { "description": "Treat as an open set.", "type": "string", "enum": [ "matched", "in_transit" ] } }, "type": "object" }, "ReconciliationSideTotals": { "required": [ "count", "total", "matched_count", "matched_total", "in_transit_count", "in_transit_total" ], "properties": { "count": { "type": "integer", "example": 3 }, "total": { "type": "string", "example": "9000.00" }, "matched_count": { "type": "integer", "example": 3 }, "matched_total": { "type": "string", "example": "9000.00" }, "in_transit_count": { "type": "integer", "example": 0 }, "in_transit_total": { "type": "string", "example": "0.00" } }, "type": "object" }, "ReconciliationWorkspaceResource": { "description": "Both sides of a treasury account over a range of days, with the active matches that hold their lines and each side's totals, and how far the account's bank reconciliation has gone.", "required": [ "treasury_account", "bank_fees_posting_account", "currency", "from", "to", "statement_lines", "ledger_lines", "matches", "totals", "bank_reconciliation", "pre_start_balance" ], "properties": { "treasury_account": { "required": [ "id", "name", "kind", "currency", "accounting_account_id", "accounting_center_id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "example": "Banco VES" }, "kind": { "type": "string", "enum": [ "bank", "wallet", "cash", "credit_card" ] }, "currency": { "type": "string", "example": "VES" }, "accounting_account_id": { "description": "The account's accounting account: what the bank fee shortcut credits.", "type": "string", "format": "uuid" }, "accounting_center_id": { "description": "The account's accounting center, credited with it.", "type": "string", "format": "uuid" } }, "type": "object" }, "bank_fees_posting_account": { "description": "The company's bank fees posting account, which the bank fee shortcut debits; null while the company has no active one pointing to an active expense account and an active center of its own.", "required": [ "account_id", "center_id" ], "properties": { "account_id": { "type": "string", "format": "uuid" }, "center_id": { "type": "string", "format": "uuid" } }, "type": "object", "nullable": true }, "currency": { "type": "string", "example": "VES" }, "from": { "type": "string", "format": "date", "example": "2026-09-01" }, "to": { "type": "string", "format": "date", "example": "2026-09-30" }, "statement_lines": { "description": "By operation day, then creation, then file row, then id.", "type": "array", "items": { "$ref": "#/components/schemas/ReconciliationStatementLineResource" } }, "ledger_lines": { "description": "By day, then entry code, then id.", "type": "array", "items": { "$ref": "#/components/schemas/ReconciliationLedgerLineResource" } }, "matches": { "description": "Every active match holding a line of the range, once each, by when it was matched, then id. A member dated outside the range keeps the day and amount it was matched with.", "type": "array", "items": { "$ref": "#/components/schemas/ReconciliationMatchResource" } }, "totals": { "required": [ "statement", "ledger" ], "properties": { "statement": { "$ref": "#/components/schemas/ReconciliationSideTotals" }, "ledger": { "$ref": "#/components/schemas/ReconciliationSideTotals" } }, "type": "object" }, "bank_reconciliation": { "description": "The account's bank reconciliation (ADR 0268); null until it is started.", "required": [ "start_month", "closed_through", "frozen_through" ], "properties": { "start_month": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$", "example": "2026-09" }, "closed_through": { "description": "The latest closed month; every month from the start through it is closed. Null while none is.", "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$", "example": "2026-09", "nullable": true }, "frozen_through": { "description": "The closed-through month's last day: a match whose lines are all dated on or before it can be neither made nor undone.", "type": "string", "format": "date", "example": "2026-09-30", "nullable": true } }, "type": "object", "nullable": true }, "pre_start_balance": { "description": "The books' balance before the account's bank reconciliation starts, which the opening line may be matched with (`pre_start_balance: true` on a match); null until it is started.", "required": [ "date", "amount", "state", "match_id" ], "properties": { "date": { "description": "The day before the start month.", "type": "string", "format": "date", "example": "2026-08-31" }, "amount": { "description": "Every ledger line of the account dated on or before that day, as it stands now; signed, in the account's currency.", "type": "string", "example": "100000.00" }, "state": { "description": "Treat as an open set.", "type": "string", "enum": [ "matched", "in_transit" ] }, "match_id": { "description": "The active match that holds it; null exactly when it is in transit.", "type": "string", "format": "uuid", "nullable": true } }, "type": "object", "nullable": true } }, "type": "object" }, "ReconciliationSuggestionReason": { "description": "Why a suggestion is proposed.", "required": [ "codes", "days_apart" ], "properties": { "codes": { "description": "Treat as an open set: amount_equal or amount_sum_equal; same_day, date_within_five_days or since_previous_business_day; reference_equal or reference_partial when the statement line's reference matches one of the ledger line's; reversal_pair.", "type": "array", "items": { "type": "string", "enum": [ "amount_equal", "amount_sum_equal", "same_day", "date_within_five_days", "since_previous_business_day", "reference_equal", "reference_partial", "reversal_pair" ] }, "example": [ "amount_equal", "same_day", "reference_equal" ] }, "days_apart": { "description": "Whole days between the statement line and the ledger line (exact), from the earliest member to the statement line's day (group), or between the earliest line of the entry and of its reversal (reversal pair).", "type": "integer", "example": 0, "minimum": 0 } }, "type": "object" }, "ReconciliationSuggestionResource": { "description": "A Reconciliation Suggestion: lines of both sides that would make a balanced match. Accept it by creating a match with its two lists of ids.", "required": [ "kind", "statement_line_ids", "ledger_line_ids", "amount", "score", "reason" ], "properties": { "kind": { "description": "Treat as an open set.", "type": "string", "enum": [ "exact", "group", "reversal_pair" ] }, "statement_line_ids": { "description": "The statement line suggested for; empty for a reversal pair.", "type": "array", "items": { "type": "string", "format": "uuid" } }, "ledger_line_ids": { "description": "Ordered by day, then id. One line for an exact suggestion; 2 to 5 lines for a group drawn from at most 12 candidates, or every candidate (up to 500) when they add up exactly; every line of an entry and of its reversal for a pair.", "type": "array", "items": { "type": "string", "format": "uuid" } }, "amount": { "description": "What each side sums to: signed, positive is money in, in the account's currency; 0.00 for a reversal pair.", "type": "string", "example": "6600.00" }, "score": { "description": "Ranks suggestions of one kind. Exact: 60 less 10 per day apart, plus 40 for an equal reference or 20 for a partial one (10 to 100). Group: 50 when every member is dated the statement line's day, 30 otherwise. Reversal pair: 100.", "type": "integer", "example": 100, "maximum": 100, "minimum": 0 }, "reason": { "$ref": "#/components/schemas/ReconciliationSuggestionReason" } }, "type": "object" }, "ReconciliationStatementLineSuggestions": { "required": [ "statement_line_id", "suggestions" ], "properties": { "statement_line_id": { "type": "string", "format": "uuid" }, "suggestions": { "description": "Every exact suggestion first (at most 5, by score, days apart, day and id), then every group (at most 3, by score, size and members).", "type": "array", "items": { "$ref": "#/components/schemas/ReconciliationSuggestionResource" } } }, "type": "object" }, "ReconciliationSuggestionsResource": { "description": "The Reconciliation Suggestions over the in-transit lines of a treasury account's window.", "required": [ "treasury_account_id", "currency", "from", "to", "statement_lines", "reversal_pairs" ], "properties": { "treasury_account_id": { "type": "string", "format": "uuid" }, "currency": { "type": "string", "example": "VES" }, "from": { "type": "string", "format": "date", "example": "2026-09-01" }, "to": { "type": "string", "format": "date", "example": "2026-09-30" }, "statement_lines": { "description": "Only the in-transit statement lines with a suggestion, in the workspace's order.", "type": "array", "items": { "$ref": "#/components/schemas/ReconciliationStatementLineSuggestions" } }, "reversal_pairs": { "description": "Entries whose in-transit lines cancel out with those of their reversal, by the entry's first line.", "type": "array", "items": { "$ref": "#/components/schemas/ReconciliationSuggestionResource" } } }, "type": "object" }, "ReconciliationMatchUnbalancedProblem": { "description": "The statement lines and the ledger lines of a match sum differently.", "required": [ "title", "status", "detail", "error_code", "errors", "currency", "statement_total", "ledger_total", "difference" ], "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string" }, "error_code": { "type": "string", "enum": [ "reconciliation_match_unbalanced" ] }, "errors": { "description": "Always null.", "type": "object", "nullable": true }, "currency": { "type": "string", "example": "VES" }, "statement_total": { "type": "string", "example": "9000.00" }, "ledger_total": { "description": "What the book side sums to: its ledger lines and the balance before the start when held.", "type": "string", "example": "6000.00" }, "difference": { "description": "The statement total minus the ledger total.", "type": "string", "example": "3000.00" } }, "type": "object" }, "ReconciliationLineAlreadyMatchedProblem": { "description": "A line is already in an active match.", "required": [ "title", "status", "detail", "error_code", "errors", "lines" ], "properties": { "title": { "type": "string", "example": "Conflict" }, "status": { "type": "integer", "example": 409 }, "detail": { "type": "string" }, "error_code": { "type": "string", "enum": [ "reconciliation_line_already_matched" ] }, "errors": { "description": "Always null.", "type": "object", "nullable": true }, "lines": { "description": "Each line already matched, with the match that holds it; empty when a concurrent match took one of the lines first.", "type": "array", "items": { "required": [ "type", "id", "match_id" ], "properties": { "type": { "description": "Treat as an open set. `pre_start` is the books' balance before the start, by the treasury account's id.", "type": "string", "enum": [ "statement_line", "ledger_line", "pre_start" ] }, "id": { "type": "string", "format": "uuid" }, "match_id": { "type": "string", "format": "uuid" } }, "type": "object" } } }, "type": "object" }, "ReconciliationLinesNotInTreasuryAccountProblem": { "description": "Some lines are not statement lines of the treasury account, or not ledger lines on its accounting account and currency that move its balance.", "required": [ "title", "status", "detail", "error_code", "errors", "lines" ], "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string" }, "error_code": { "type": "string", "enum": [ "reconciliation_lines_not_in_treasury_account" ] }, "errors": { "description": "Always null.", "type": "object", "nullable": true }, "lines": { "type": "array", "items": { "required": [ "type", "id" ], "properties": { "type": { "description": "Treat as an open set.", "type": "string", "enum": [ "statement_line", "ledger_line" ] }, "id": { "type": "string", "format": "uuid" } }, "type": "object" } } }, "type": "object" }, "ReconciliationWorkspaceRangeTooLongProblem": { "description": "The range ends before it starts or spans more days than the workspace shows.", "required": [ "title", "status", "detail", "error_code", "errors", "max_days" ], "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string" }, "error_code": { "type": "string", "enum": [ "reconciliation_workspace_range_too_long" ] }, "errors": { "description": "Always null.", "type": "object", "nullable": true }, "max_days": { "type": "integer", "example": 92 } }, "type": "object" }, "ReconciliationWorkspaceTooManyLinesProblem": { "description": "One side holds more lines in the range than the workspace shows at once; a shorter range answers.", "required": [ "title", "status", "detail", "error_code", "errors", "side", "limit" ], "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string" }, "error_code": { "type": "string", "enum": [ "reconciliation_workspace_too_many_lines" ] }, "errors": { "description": "Always null.", "type": "object", "nullable": true }, "side": { "type": "string", "enum": [ "statement", "ledger" ] }, "limit": { "type": "integer", "example": 2000 } }, "type": "object" }, "TreasuryTransferResource": { "description": "A treasury transfer as the list shows it, with its Responsable, labels and recording time. What it is worth in each book, its Rate Snapshot and its differences come from the transfer as recorded, never revalued.", "required": [ "id", "status", "source_treasury_account_id", "source_treasury_account_name", "delivered_amount", "delivered_currency", "destination_treasury_account_id", "destination_treasury_account_name", "received_amount", "received_currency", "operation_date", "credit_date", "reference", "counterparty", "recorded_by_user_id", "recorded_by_api_key_id", "recorded_at", "cancelled_at", "transaction_code", "cancellation_transaction_code", "responsible_user_id", "responsible_user_name", "labels", "fees", "kind", "effective_rate", "valuation", "rate_snapshot", "differences" ], "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "posted", "cancelled" ] }, "source_treasury_account_id": { "type": "string", "format": "uuid" }, "source_treasury_account_name": { "type": "string", "example": "Efectivo USD", "nullable": true }, "delivered_amount": { "type": "string", "example": "1000.00" }, "delivered_currency": { "type": "string", "enum": [ "USD", "VES", "USDT", "EUR", "DOP" ] }, "destination_treasury_account_id": { "type": "string", "format": "uuid" }, "destination_treasury_account_name": { "type": "string", "example": "Banco VES", "nullable": true }, "received_amount": { "type": "string", "example": "150000.00" }, "received_currency": { "type": "string", "enum": [ "USD", "VES", "USDT", "EUR", "DOP" ] }, "operation_date": { "type": "string", "format": "date", "example": "2026-09-26" }, "credit_date": { "type": "string", "format": "date", "example": "2026-09-27" }, "reference": { "type": "string", "nullable": true }, "counterparty": { "type": "string", "nullable": true }, "recorded_by_user_id": { "type": "string", "example": "42", "nullable": true }, "recorded_by_api_key_id": { "type": "string", "nullable": true }, "recorded_at": { "description": "When the transfer was recorded, in UTC; null only for a transfer stored without that time.", "type": "string", "format": "date-time", "example": "2026-09-26T18:30:00+00:00", "nullable": true }, "cancelled_at": { "type": "string", "format": "date-time", "example": "2026-09-27T15:00:00+00:00", "nullable": true }, "transaction_code": { "description": "The code of the posted entry.", "type": "string", "nullable": true }, "cancellation_transaction_code": { "description": "The code of the entry that inverted it on cancellation.", "type": "string", "nullable": true }, "responsible_user_id": { "description": "The user id of its Responsable; null when it has none.", "type": "string", "example": "57", "nullable": true }, "responsible_user_name": { "description": "The Responsable's name, also of a user no longer in the company; null when it has none or the user no longer exists.", "type": "string", "example": "Ana Pérez", "nullable": true }, "labels": { "description": "Its labels by name, archived ones flagged; empty when it has none.", "type": "array", "items": { "required": [ "id", "name", "tone", "archived" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "example": "Urgente" }, "tone": { "type": "string", "example": "red" }, "archived": { "type": "boolean" } }, "type": "object" } }, "fees": { "description": "The Transfer Fees in the order they were charged; empty when there are none.", "type": "array", "items": { "required": [ "id", "treasury_account_id", "treasury_account_name", "amount", "currency" ], "properties": { "id": { "type": "string", "format": "uuid" }, "treasury_account_id": { "description": "The source or the destination treasury account the fee left.", "type": "string", "format": "uuid" }, "treasury_account_name": { "description": "Its current name, null when the account no longer exists.", "type": "string", "nullable": true }, "amount": { "description": "In the currency of the account it left.", "type": "string", "example": "1.00" }, "currency": { "type": "string", "enum": [ "USD", "VES", "USDT", "EUR", "DOP" ] } }, "type": "object" } }, "kind": { "description": "`exchange` when the two accounts keep different currencies (a Currency Exchange).", "type": "string", "enum": [ "same_currency", "exchange" ] }, "effective_rate": { "description": "The Effective Rate of an exchange at 8 decimals, quoted like the official pair — units of the quote per unit of the base, where the base is USDT against USD or VES and USD against VES: bolívares per USD, bolívares per USDT or USD per USDT — agreed by whoever recorded it; null for a transfer in one currency.", "type": "string", "example": "150.00000000", "nullable": true }, "valuation": { "description": "What the transfer is worth in each of the company's books: the carrying amount its source relieved and what its destination posted.", "required": [ "functional_currency", "reporting_currency", "source_relieved_functional", "source_relieved_reporting", "destination_functional", "destination_reporting" ], "properties": { "functional_currency": { "type": "string", "example": "VES" }, "reporting_currency": { "type": "string", "example": "USD" }, "source_relieved_functional": { "type": "string", "example": "100000.00" }, "source_relieved_reporting": { "type": "string", "example": "1000.00" }, "destination_functional": { "type": "string", "example": "150000.00" }, "destination_reporting": { "type": "string", "example": "1153.85" } }, "type": "object" }, "rate_snapshot": { "description": "The Rate Snapshot the transfer took (ADR 0202): always for an exchange, where it is `negotiated` with the Effective Rate as `agreed_rate` next to the official rate it references; otherwise only when a source crossed zero or a fee needed its official value. Null when it took none.", "required": [ "currency", "rate", "rate_reference", "rate_rule", "rate_value_date", "rate_known_at", "rate_origin", "agreed_rate", "agreed_by", "agreed_by_api_key_id" ], "properties": { "currency": { "description": "The money the official rate valued.", "type": "string", "example": "USD" }, "rate": { "description": "The official USD/VES rate; 1.00000000 when nothing converts.", "type": "string", "example": "130.00000000" }, "rate_reference": { "description": "The official rate row; null for an identity valuation.", "type": "string", "nullable": true }, "rate_rule": { "type": "string", "enum": [ "identity", "publication_instant", "value_date", "negotiated" ] }, "rate_value_date": { "type": "string", "format": "date", "example": "2026-09-26" }, "rate_known_at": { "type": "string", "format": "date-time", "example": "2026-09-26T20:00:00+00:00", "nullable": true }, "rate_origin": { "type": "string", "nullable": true, "enum": [ "ingested", "manual" ] }, "agreed_rate": { "type": "string", "example": "150.00000000", "nullable": true }, "agreed_by": { "description": "The user who agreed the rate, or who owns the API key that did.", "type": "string", "example": "42", "nullable": true }, "agreed_by_api_key_id": { "type": "string", "nullable": true } }, "type": "object", "nullable": true }, "differences": { "description": "The realized differences the entry posts, one per origin leg, book and cause, signed from the company's side: positive is a gain, negative a loss, each in its book's currency. Empty when there are none.", "type": "array", "items": { "required": [ "origin_leg", "fee_id", "book", "cause", "amount", "currency" ], "properties": { "origin_leg": { "type": "string", "enum": [ "source", "destination", "fee" ] }, "fee_id": { "description": "The fee a `fee` difference originates on; null otherwise.", "type": "string", "format": "uuid", "nullable": true }, "book": { "type": "string", "enum": [ "functional", "reporting" ] }, "cause": { "type": "string", "enum": [ "treasury_currency", "agreed_rate" ] }, "amount": { "type": "string", "example": "30000.00" }, "currency": { "type": "string", "example": "VES" } }, "type": "object" } } }, "type": "object" }, "TreasuryTransferDetailResource": { "description": "A treasury transfer as its detail shows it: the list item plus the rate indicator of an exchange.", "allOf": [ { "$ref": "#/components/schemas/TreasuryTransferResource" }, { "required": [ "indicator" ], "properties": { "indicator": { "description": "Informative only, never posted: how the Effective Rate of an exchange compares with the official rate it references and with the latest Management Reference of its side observed by the end of its operation date in the company's timezone. Null for a transfer in one currency and for an exchange between USD and USDT, which has no bolívar side.", "required": [ "pair", "reference_side", "management_reference", "gaps" ], "properties": { "pair": { "description": "The dollar side against the bolívar: USD/VES or USDT/VES.", "type": "string", "example": "USD/VES" }, "reference_side": { "description": "The side of the Management Reference the exchange is compared with, from the company's side: `sell` when it sells its dollar side, `buy` when it buys it. Present even when `management_reference` is null.", "type": "string", "example": "sell", "enum": [ "buy", "sell" ] }, "management_reference": { "description": "The latest non-superseded Management Reference of the pair, of the side in `reference_side`; null when none of that side was observed (the other side is never used), or when the viewer lacks backoffice.accounting.settings.exchange-rates.view.", "required": [ "id", "rate", "side", "channel", "source", "observed_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "rate": { "type": "string", "example": "145.00000000" }, "side": { "type": "string", "enum": [ "buy", "sell" ] }, "channel": { "type": "string", "example": "Binance P2P" }, "source": { "type": "string", "example": "manual" }, "observed_at": { "type": "string", "format": "date-time", "example": "2026-09-26T13:00:00+00:00" } }, "type": "object", "nullable": true }, "gaps": { "description": "Each gap is X − Y at 8 decimals and its percentage of Y, half-up at 2 decimals, both signed. The reference gaps are null without a management reference. Each gap of the Effective Rate carries an `outcome` for the company: a higher Effective Rate is `favorable` when the exchange sells its dollar side and `unfavorable` when it buys it, and the reverse for a lower one; `none` when the difference is zero at 8 decimals.", "required": [ "effective_vs_official", "effective_vs_reference", "official_vs_reference" ], "properties": { "effective_vs_official": { "required": [ "difference", "percentage", "outcome" ], "properties": { "difference": { "type": "string", "example": "20.00000000" }, "percentage": { "type": "string", "example": "15.38" }, "outcome": { "type": "string", "example": "favorable", "enum": [ "favorable", "unfavorable", "none" ] } }, "type": "object" }, "effective_vs_reference": { "required": [ "difference", "percentage", "outcome" ], "properties": { "difference": { "type": "string", "example": "5.00000000" }, "percentage": { "type": "string", "example": "3.45" }, "outcome": { "type": "string", "example": "favorable", "enum": [ "favorable", "unfavorable", "none" ] } }, "type": "object", "nullable": true }, "official_vs_reference": { "description": "No outcome: it describes the market.", "required": [ "difference", "percentage" ], "properties": { "difference": { "type": "string", "example": "-15.00000000" }, "percentage": { "type": "string", "example": "-10.34" } }, "type": "object", "nullable": true } }, "type": "object" } }, "type": "object", "nullable": true } }, "type": "object" } ] }, "TreasuryTransferResponsibleAcknowledgement": { "description": "Always {}", "type": "object" }, "InvalidListSortProblem": { "description": "invalid_list_sort (422, MER-3348): a list was asked for a sort_by that is not one of its columns, or a sort_order other than asc or desc; errors names the parameter refused.", "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string", "example": "Unprocessable Entity" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string", "example": "La lista no se puede ordenar por ." }, "error_code": { "type": "string", "enum": [ "invalid_list_sort" ] }, "errors": { "description": "Exactly one member: the parameter refused, with its one message.", "properties": { "sort_by": { "description": "The message of a refused sort_by.", "type": "array", "items": { "type": "string" } }, "sort_order": { "description": "The message of a refused sort_order.", "type": "array", "items": { "type": "string" } } }, "type": "object" } }, "type": "object" }, "StorefrontBuyerVerification": { "required": [ "id", "code", "wa_me_url", "message", "verification_phone_e164", "expires_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "wa_me_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "verification_phone_e164": { "description": "Service number that receives the verification, never the buyer phone.", "type": "string" }, "expires_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "StorefrontBuyerVerificationState": { "required": [ "status", "last_refusal", "expires_at" ], "properties": { "status": { "type": "string" }, "last_refusal": { "properties": { "reason": { "type": "string" }, "at": { "type": "string", "format": "date-time" } }, "type": "object", "nullable": true }, "expires_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "StorefrontBuyer": { "required": [ "id", "client_id", "name", "email", "profile_complete" ], "properties": { "id": { "type": "string", "format": "uuid" }, "client_id": { "type": "string", "format": "uuid", "nullable": true }, "name": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true }, "profile_complete": { "type": "boolean" } }, "type": "object" }, "StorefrontCatalogImage": { "required": [ "thumbnail_url", "original_url", "alt_text" ], "properties": { "thumbnail_url": { "type": "string" }, "original_url": { "type": "string" }, "alt_text": { "type": "string", "nullable": true } }, "type": "object" }, "StorefrontCatalogCategoryRef": { "required": [ "id", "name" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "type": "object" }, "StorefrontCatalogVariant": { "required": [ "item_id", "code", "sku", "name", "options", "images" ], "properties": { "item_id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "sku": { "type": "string", "nullable": true }, "name": { "type": "string" }, "options": { "type": "array", "items": { "required": [ "name", "value" ], "properties": { "name": { "type": "string" }, "value": { "type": "string" } }, "type": "object" } }, "images": { "type": "array", "items": { "$ref": "#/components/schemas/StorefrontCatalogImage" } } }, "type": "object" }, "StorefrontCatalogProduct": { "required": [ "type", "id", "name", "option_names", "option_values", "category", "cover_image", "variants" ], "properties": { "type": { "type": "string", "enum": [ "model", "item" ] }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "option_names": { "type": "array", "items": { "type": "string" } }, "option_values": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "category": { "$ref": "#/components/schemas/StorefrontCatalogCategoryRef" }, "cover_image": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/StorefrontCatalogImage" } ] }, "variants": { "type": "array", "items": { "$ref": "#/components/schemas/StorefrontCatalogVariant" } } }, "type": "object" }, "StorefrontCatalogCategory": { "required": [ "id", "name", "description", "product_count" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "product_count": { "type": "integer" } }, "type": "object" }, "StorefrontCatalogCategoriesResponse": { "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/StorefrontCatalogCategory" } } }, "type": "object" }, "StorefrontCatalogProductsPage": { "required": [ "data", "current_page", "last_page", "per_page", "total" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/StorefrontCatalogProduct" } }, "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" } }, "type": "object" }, "StorefrontCatalogProblem": { "required": [ "title", "status", "detail" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "error_code": { "type": "string", "nullable": true } }, "type": "object" }, "StorefrontOffer": { "required": [ "item_id", "price", "price_ves", "rate", "rate_unavailable", "purchasable", "stock_status" ], "properties": { "item_id": { "type": "string", "format": "uuid" }, "price": { "description": "source_price from SalePriceResolver (amount string + origin currency); null when unpriced", "required": [ "amount", "currency" ], "properties": { "amount": { "type": "string", "example": "25.00" }, "currency": { "type": "string", "example": "USD" } }, "type": "object", "nullable": true }, "price_ves": { "description": "Bolívares when origin is USD and a rate exists; null when origin is VES or rate unavailable", "type": "string", "example": "1000.00", "nullable": true }, "rate": { "required": [ "value_date", "rate" ], "properties": { "value_date": { "type": "string", "format": "date" }, "rate": { "type": "string", "example": "40.00000000" } }, "type": "object", "nullable": true }, "rate_unavailable": { "type": "boolean" }, "purchasable": { "type": "boolean" }, "stock_status": { "type": "string", "enum": [ "in_stock", "low_stock", "out_of_stock" ] } }, "type": "object" }, "StorefrontOffersResponse": { "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/StorefrontOffer" } } }, "type": "object" }, "WebOrderPaymentReport": { "required": [ "id", "ordinal", "reference", "reported_at", "active", "evidence_sha256", "evidence_mime", "preview" ], "properties": { "id": { "type": "string", "format": "uuid" }, "ordinal": { "type": "integer", "maximum": 3, "minimum": 1 }, "reference": { "type": "string" }, "reason": { "type": "string", "nullable": true }, "reported_at": { "type": "string", "format": "date-time" }, "active": { "type": "boolean" }, "evidence_sha256": { "type": "string" }, "evidence_mime": { "type": "string" }, "preview": { "description": "Buyer-scoped ERP route; never an object-store URL.", "type": "string" } }, "type": "object" }, "WebOrderReported": { "allOf": [ { "$ref": "#/components/schemas/WebOrder" }, { "required": [ "review_due_at", "payment_report" ], "properties": { "review_due_at": { "type": "string", "format": "date-time" }, "payment_report": { "$ref": "#/components/schemas/WebOrderPaymentReport" } }, "type": "object" } ] }, "WebOrderPaymentProblem": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/StorefrontCatalogProblem" }, { "required": [ "error_code", "errors" ], "properties": { "errors": { "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" } ] }, "WebOrderBuyerSessionRequired": { "required": [ "error_code", "detail" ], "properties": { "error_code": { "type": "string", "enum": [ "buyer_session_required" ] }, "detail": { "type": "string" } }, "type": "object" }, "WebOrderCart": { "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "required": [ "item_id", "quantity" ], "properties": { "item_id": { "type": "string", "format": "uuid" }, "quantity": { "description": "Positive base-unit decimal string, up to four decimals", "type": "string" } }, "type": "object" }, "maxItems": 100, "minItems": 1 }, "rail_id": { "type": "string", "format": "uuid", "nullable": true } }, "type": "object" }, "WebOrderReserve": { "allOf": [ { "$ref": "#/components/schemas/WebOrderCart" }, { "required": [ "quote" ], "properties": { "quote": { "type": "string" }, "whatsapp_notice_opt_in": { "description": "The buyer's consent to WhatsApp notices of this order only, distinct from her profile consent. Absent means false, and declining never blocks the order.", "type": "boolean" }, "whatsapp_notice_consent_version": { "description": "The version of the copy she accepted, required when whatsapp_notice_opt_in is true and refused otherwise. Version 1 reads «Quiero recibir por WhatsApp los avisos de este pedido de [comercio]».", "type": "string", "enum": [ "1" ] } }, "type": "object" } ] }, "WebOrderPublicLine": { "required": [ "item_id", "item_name", "quantity", "unit_price", "discount_percentage", "tax_percentage", "subtotal", "tax_amount", "total" ], "properties": { "item_id": { "type": "string", "format": "uuid" }, "item_name": { "type": "string" }, "quantity": { "type": "string" }, "unit_price": { "type": "string" }, "discount_percentage": { "type": "string" }, "tax_percentage": { "type": "string" }, "subtotal": { "description": "Net of discount, like totals.subtotal.", "allOf": [ { "$ref": "#/components/schemas/WebOrderMoney" } ] }, "tax_amount": { "description": "Informational: totals stay authoritative.", "allOf": [ { "$ref": "#/components/schemas/WebOrderMoney" } ] }, "total": { "$ref": "#/components/schemas/WebOrderMoney" } }, "type": "object", "additionalProperties": false }, "WebOrderPublicTerms": { "description": "The frozen commercial terms a buyer reads, as a whitelist of what the order stores. A value an old row never froze answers null.", "required": [ "lines", "totals", "rate", "rail" ], "properties": { "lines": { "type": "array", "items": { "$ref": "#/components/schemas/WebOrderPublicLine" } }, "totals": { "required": [ "subtotal", "taxes", "total", "counterpart" ], "properties": { "subtotal": { "$ref": "#/components/schemas/WebOrderMoney" }, "taxes": { "$ref": "#/components/schemas/WebOrderMoney" }, "total": { "$ref": "#/components/schemas/WebOrderMoney" }, "counterpart": { "required": [ "currency", "subtotal", "taxes", "total" ], "properties": { "currency": { "type": "string" }, "subtotal": { "type": "string" }, "taxes": { "type": "string" }, "total": { "type": "string" } }, "type": "object", "nullable": true, "additionalProperties": false } }, "type": "object", "additionalProperties": false }, "rate": { "required": [ "currency", "functional_rate", "reporting_rate", "rate_value_date" ], "properties": { "currency": { "type": "string" }, "functional_rate": { "type": "string" }, "reporting_rate": { "type": "string" }, "rate_value_date": { "type": "string", "format": "date" } }, "type": "object", "additionalProperties": false }, "rail": { "required": [ "id", "name", "class", "currency", "requires_reference", "settle_amount", "settlement_rate" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "class": { "type": "string" }, "currency": { "type": "string" }, "requires_reference": { "type": "boolean" }, "settle_amount": { "$ref": "#/components/schemas/WebOrderMoney" }, "settlement_rate": { "description": "The rate that made settle_amount; null for a rail in the document currency and on orders reserved before MER-5429.", "required": [ "rate", "value_date" ], "properties": { "rate": { "type": "string" }, "value_date": { "type": "string", "format": "date" } }, "type": "object", "nullable": true, "additionalProperties": false } }, "type": "object", "nullable": true, "additionalProperties": false } }, "type": "object", "additionalProperties": false }, "WebOrderRailOffer": { "description": "A rail a buyer can select, with what it would settle through it. A rail with no settle amount is not offered.", "required": [ "id", "name", "class", "currency", "requires_reference", "settle_amount" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "class": { "type": "string" }, "currency": { "type": "string" }, "requires_reference": { "type": "boolean" }, "settle_amount": { "$ref": "#/components/schemas/WebOrderMoney" } }, "type": "object", "additionalProperties": false }, "WebOrderQuote": { "required": [ "quote", "preview", "label", "expires_at", "terms", "rails", "availability", "reservation" ], "properties": { "quote": { "type": "string" }, "preview": { "type": "boolean" }, "label": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" }, "terms": { "$ref": "#/components/schemas/WebOrderPublicTerms" }, "rails": { "description": "What the buyer can select, outside the signed terms. A rail never offered answers rail_unavailable.", "type": "array", "items": { "$ref": "#/components/schemas/WebOrderRailOffer" } }, "availability": { "description": "On a quote she can reserve with, one row per line, outside the signed terms: whether the stock covers it now. Informational; the reservation locks still decide, and an item never stocked is always available. Always empty on a preview, which reveals nothing about stock.", "type": "array", "items": { "required": [ "item_id", "available" ], "properties": { "item_id": { "type": "string", "format": "uuid" }, "available": { "type": "boolean" } }, "type": "object", "additionalProperties": false } }, "reservation": { "description": "On a quote she can reserve with: the reservation TTL in force at the quote's instant and the deadline a reservation placed then would get, projected by the server. The TTL is signed into the quote, and reserve answers 409 QUOTE_STALE when the TTL in force by then differs. The created order's expires_at stays authoritative: the reserve instant plus ttl_minutes. Null on a preview, and on a buyer quote whose channel has no reservation policy in force or cannot guarantee its open time; reserving that quote answers reservation_policy_missing or reservation_policy_open_time_unavailable.", "required": [ "ttl_minutes", "deadline_at" ], "properties": { "ttl_minutes": { "type": "integer", "maximum": 20160, "minimum": 1 }, "deadline_at": { "type": "string", "format": "date-time" } }, "type": "object", "nullable": true, "additionalProperties": false } }, "type": "object" }, "WebOrder": { "required": [ "id", "display_id", "status", "version", "rail_id", "expires_at", "review_due_at", "policy_version", "terms" ], "properties": { "id": { "type": "string", "format": "uuid" }, "display_id": { "type": "string" }, "status": { "type": "string" }, "version": { "type": "integer" }, "rail_id": { "type": "string", "format": "uuid", "nullable": true }, "expires_at": { "type": "string", "format": "date-time" }, "review_due_at": { "description": "Fixed at the first report; a correction never moves it.", "type": "string", "format": "date-time", "nullable": true }, "policy_version": { "type": "integer" }, "terms": { "$ref": "#/components/schemas/WebOrderPublicTerms" } }, "type": "object" }, "WebOrderDetail": { "allOf": [ { "$ref": "#/components/schemas/WebOrder" }, { "required": [ "available_rails" ], "properties": { "available_rails": { "description": "The rails this order can change to, at today's rates over its frozen total, as PATCH rail would freeze them. Empty unless it awaits payment before its deadline; a blocked rate leaves its rail out.", "type": "array", "items": { "$ref": "#/components/schemas/WebOrderRailOffer" } } }, "type": "object" } ] }, "WebOrderReserveProblem": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/WebOrderPaymentProblem" }, { "properties": { "web_order_id": { "description": "With buyer_has_live_order: her live order on this channel.", "type": "string", "format": "uuid" }, "insufficient_stock_items": { "description": "With insufficient_stock: every short line, by item only. No quantity or location reaches a buyer.", "type": "array", "items": { "required": [ "item_id" ], "properties": { "item_id": { "type": "string", "format": "uuid" } }, "type": "object", "additionalProperties": false }, "minItems": 1 } }, "type": "object" } ] }, "PaymentAmountDue": { "required": [ "contracted_seats", "price_per_user_usd", "amount_usd", "amount_ves", "rate", "rate_published_at", "rate_effective_date", "calculated_at" ], "properties": { "contracted_seats": { "type": "integer", "maximum": 50, "minimum": 1 }, "price_per_user_usd": { "type": "string", "pattern": "^[0-9]+[.][0-9]{2}$", "example": "20.00" }, "amount_usd": { "type": "string", "pattern": "^[0-9]+[.][0-9]{2}$", "example": "60.00" }, "amount_ves": { "type": "string", "pattern": "^[0-9]+[.][0-9]{2}$", "example": "3000.00" }, "rate": { "type": "string", "pattern": "^[0-9]+[.][0-9]{8}$", "example": "50.00000000" }, "rate_published_at": { "description": "Server-known publication instant; first_seen_at, never confirmed_at.", "type": "string", "format": "date-time" }, "rate_effective_date": { "type": "string", "format": "date" }, "calculated_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "PaymentReportInput": { "required": [ "id", "reference", "paid_on", "amount_ves_reported", "proof" ], "properties": { "requested_seats": { "description": "Target Pro seats for a Free upgrade; frozen with the report until validation.", "type": "integer", "maximum": 50, "minimum": 1 }, "id": { "description": "Client-generated canonical UUID v7.", "type": "string", "format": "uuid", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$" }, "reference": { "description": "Letters, digits, whitespace and hyphens; trim, uppercase and remove whitespace/hyphens preserving leading zeroes.", "type": "string", "pattern": "^(?=.*[A-Za-z0-9])[A-Za-z0-9\\s-]+$", "maxLength": 100 }, "paid_on": { "description": "Valid YYYY-MM-DD calendar date.", "type": "string", "format": "date" }, "amount_ves_reported": { "description": "Positive reported VES decimal string, at most two decimals and 22 integer digits. Server-owned quote fields are prohibited.", "type": "string", "pattern": "^(?!0+(?:[.]0{1,2})?$)[0-9]{1,22}(?:[.][0-9]{1,2})?$" }, "proof": { "description": "JPG/JPEG, PNG, WEBP or PDF, matching sniffed MIME and filename extension, at most 15728640 bytes (15 MiB). Private storage only.", "type": "string", "format": "binary" } }, "type": "object", "additionalProperties": false }, "PaymentReportResponse": { "required": [ "id", "status", "access_status", "amount_due", "amount_ves_reported", "reference", "paid_on" ], "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "pending", "validated", "rejected" ] }, "access_status": { "type": "string", "enum": [ "sin_reporte", "en_validacion", "activa", "bloqueada", "acceso_gestionado" ] }, "amount_due": { "$ref": "#/components/schemas/PaymentAmountDue" }, "amount_ves_reported": { "type": "string", "pattern": "^[0-9]+[.][0-9]{2}$" }, "reference": { "type": "string", "maxLength": 100 }, "paid_on": { "type": "string", "format": "date" } }, "type": "object" }, "PaymentReportValidation": { "required": [ "message", "errors" ], "properties": { "message": { "type": "string" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" }, "SubscriptionAccessState": { "required": [ "has_subscription", "plan", "access_status", "contracted_seats", "rejection_count", "gate_enabled", "can_report", "payment_availability", "amount_due", "payment_mobile", "is_holder", "covered_companies_count", "covered_companies", "active_users_count" ], "properties": { "has_subscription": { "type": "boolean" }, "is_holder": { "description": "The acting Company is the Compañía titular of the Suscripción that covers it; false when the Company has no Suscripción.", "type": "boolean" }, "covered_companies_count": { "description": "Companies covered by the Suscripción, the titular included; null when the Company has no Suscripción.", "type": "integer", "nullable": true, "minimum": 1 }, "covered_companies": { "description": "Covered Companies where the requesting user is an active member, the titular first; empty when the Company has no Suscripción.", "type": "array", "items": { "required": [ "id", "name", "is_holder" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "is_holder": { "type": "boolean" } }, "type": "object" } }, "active_users_count": { "description": "Distinct active people across every covered Company, compared with contracted_seats; null when the Company has no Suscripción.", "type": "integer", "nullable": true, "minimum": 0 }, "paid_until": { "type": "string", "format": "date", "nullable": true }, "grace_until": { "type": "string", "format": "date", "nullable": true }, "renewal_due": { "type": "boolean" }, "owner_confirmation_required": { "description": "Operational writes remain denied until an active company Superadmin explicitly confirms ownership; confirmation and payment remain available.", "type": "boolean" }, "owner_confirmed": { "description": "An explicit audited operational owner is recorded; legacy payment access does not require a historical registration.", "type": "boolean" }, "plan": { "type": "string", "nullable": true, "enum": [ "free", "pro" ] }, "access_status": { "type": "string", "enum": [ "sin_reporte", "en_validacion", "activa", "bloqueada", "acceso_gestionado" ] }, "contracted_seats": { "description": "Usuarios contratados of the Suscripción covering the company, shared by every covered Company. Null only when the company has no Suscripción.", "type": "integer", "nullable": true, "maximum": 50, "minimum": 1 }, "rejection_count": { "type": "integer", "minimum": 0 }, "gate_enabled": { "description": "Effective access gate switch. False preserves ordinary access regardless of the raw stored state.", "type": "boolean" }, "can_report": { "description": "Actual Company-scoped Superadmin capability, independent of quote availability or access state.", "type": "boolean" }, "payment_availability": { "type": "string", "enum": [ "available", "rate_unavailable", "payment_configuration_unavailable", "not_applicable" ] }, "amount_due": { "required": [ "contracted_seats", "price_per_user_usd", "amount_usd", "amount_ves", "rate", "rate_published_at", "rate_effective_date", "calculated_at" ], "properties": { "contracted_seats": { "type": "integer", "maximum": 50, "minimum": 1 }, "price_per_user_usd": { "type": "string", "pattern": "^[0-9]+[.][0-9]{2}$", "example": "20.00" }, "amount_usd": { "type": "string", "pattern": "^[0-9]+[.][0-9]{2}$", "example": "60.00" }, "amount_ves": { "type": "string", "pattern": "^[0-9]+[.][0-9]{2}$", "example": "3000.00" }, "rate": { "type": "string", "pattern": "^[0-9]+[.][0-9]{8}$", "example": "50.00000000" }, "rate_published_at": { "description": "Server-known publication instant; first_seen_at, never confirmed_at.", "type": "string", "format": "date-time" }, "rate_effective_date": { "type": "string", "format": "date" }, "calculated_at": { "type": "string", "format": "date-time" } }, "type": "object", "nullable": true }, "payment_mobile": { "required": [ "bank", "phone", "document" ], "properties": { "bank": { "type": "string" }, "phone": { "type": "string" }, "document": { "type": "string" } }, "type": "object", "nullable": true } }, "type": "object" }, "SubscriptionAccessError": { "required": [ "title", "status", "detail", "error_code" ], "properties": { "title": { "type": "string", "enum": [ "Payment Required" ] }, "status": { "type": "integer", "enum": [ 402 ] }, "detail": { "type": "string" }, "error_code": { "type": "string", "enum": [ "subscription_payment_required", "subscription_blocked", "subscription_upgrade_required" ] } }, "type": "object" }, "SubscriptionMessage": { "required": [ "message" ], "properties": { "message": { "type": "string" } }, "type": "object" }, "SubscriptionAccessDenied": { "required": [ "title", "status", "detail" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer", "enum": [ 403 ] }, "detail": { "type": "string" }, "reason": { "description": "Present when tenant role membership is denied; absent when company access is denied.", "type": "string" } }, "type": "object" }, "SubscriptionUnverifiedEmail": { "required": [ "message" ], "properties": { "message": { "type": "string" }, "status": { "type": "string", "enum": [ "email_not_verified" ] }, "detail": { "type": "string" } }, "type": "object" }, "SubscriptionProblem": { "required": [ "title", "status", "detail", "error_code", "errors" ], "properties": { "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "error_code": { "type": "string", "nullable": true }, "errors": { "type": "object", "nullable": true } }, "type": "object" } }, "responses": { "SubscriptionAccessRequired": { "description": "A Pro feature requires an upgrade, or the enabled subscription gate requires a payment report or staff assistance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionAccessError" } } } } }, "parameters": { "LedgerReportDate": { "name": "date", "in": "query", "description": "Strict calendar date; all history through this inclusive date", "required": true, "schema": { "type": "string", "format": "date", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$" } }, "GeneralLedgerAccountId": { "name": "account_id", "in": "query", "description": "Existing account UUID belonging to tenant; inactive and effective group accounts are valid. Missing, malformed or foreign accounts fail validation with 422; deletion after validation yields 404.", "required": true, "schema": { "type": "string", "format": "uuid" } }, "GeneralLedgerIncludeSubtree": { "name": "include_subtree", "in": "query", "description": "Root alone by default; true includes deduplicated effective descendants through company-local parent hierarchy. Accepted query spellings true, false, 1, 0; null, arrays and other text rejected.", "required": false, "schema": { "type": "string", "default": "false", "enum": [ "true", "false", "1", "0" ] } }, "GeneralLedgerPage": { "name": "page", "in": "query", "description": "Positive decimal integer page; fractional/scientific values, booleans, null and arrays rejected. Fixed 200 rows. Overflow preserves current_page, returns no rows and full closing as both page balances.", "required": false, "schema": { "type": "integer", "default": 1, "maximum": 2147483647, "minimum": 1 } }, "JournalFrom": { "name": "from", "in": "query", "description": "Inclusive selected line date, strict real Y-m-d; header date may differ.", "required": true, "schema": { "type": "string", "format": "date" } }, "JournalTo": { "name": "to", "in": "query", "description": "Inclusive selected line date, strict real Y-m-d, no earlier than from.", "required": true, "schema": { "type": "string", "format": "date" } }, "JournalCenter": { "name": "accounting_center_id", "in": "query", "description": "Optional company-owned historical center UUID; inactive centers remain valid. Filters selected lines only; partial entry totals may differ.", "required": false, "schema": { "type": "string", "format": "uuid", "nullable": true } }, "JournalPage": { "name": "page", "in": "query", "description": "Positive decimal integer spelling ^[1-9][0-9]*$, without signs, leading zeros, fractions, scientific notation, booleans, null or arrays. Fixed 50 distinct headers; export prohibits any page.", "required": false, "schema": { "type": "integer", "default": 1, "maximum": 2147483647, "minimum": 1 } }, "LedgerReportTenant": { "name": "tenant", "in": "path", "description": "Company UUID", "required": true, "schema": { "type": "string", "format": "uuid" } }, "LedgerReportFrom": { "name": "from", "in": "query", "description": "Strict calendar date, inclusive period start; earlier postings form opening balance", "required": true, "schema": { "type": "string", "format": "date", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$" } }, "LedgerReportTo": { "name": "to", "in": "query", "description": "Strict calendar date, inclusive period end; must be greater than or equal to from", "required": true, "schema": { "type": "string", "format": "date", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$" } }, "LedgerReportBook": { "name": "book", "in": "query", "description": "Stored ledger book; no revaluation", "required": false, "schema": { "type": "string", "default": "functional", "enum": [ "functional", "reporting" ] } }, "LedgerReportCenter": { "name": "accounting_center_id", "in": "query", "description": "Existing center belonging to tenant, including inactive centers; filters opening and period", "required": false, "schema": { "type": "string", "format": "uuid", "nullable": true } }, "LedgerReportIncludeZero": { "name": "include_zero", "in": "query", "description": "Include full account catalog. Accepted query spellings: true, false, 1, 0; arrays and other text rejected", "required": false, "schema": { "type": "string", "default": "false", "enum": [ "true", "false", "1", "0" ] } }, "PayablesAgingProvider": { "name": "provider_id", "in": "query", "description": "Existing provider belonging to tenant, including inactive providers; narrows every open document, so filtered totals no longer equal the ledger", "required": false, "schema": { "type": "string", "format": "uuid", "nullable": true } }, "PayablesAgingCurrency": { "name": "currency", "in": "query", "description": "Document currency, exact code; narrows every open document, so filtered totals no longer equal the ledger", "required": false, "schema": { "type": "string", "nullable": true, "enum": [ "USD", "VES", "USDT", "EUR", "DOP" ] } }, "PayablesAgingCenter": { "name": "accounting_center_id", "in": "query", "description": "Existing accounting center belonging to tenant, including inactive centers; narrows every open document, so filtered totals no longer equal the ledger", "required": false, "schema": { "type": "string", "format": "uuid", "nullable": true } }, "ProviderStatementFrom": { "name": "from", "in": "query", "description": "First day of the range on the company calendar, Y-m-d; every earlier movement folds into the opening balance", "required": true, "schema": { "type": "string", "format": "date" } }, "ProviderStatementTo": { "name": "to", "in": "query", "description": "Last day of the range on the company calendar, Y-m-d, on or after from; it may be after today and no movement after it is read", "required": true, "schema": { "type": "string", "format": "date" } }, "ProviderStatementCurrency": { "name": "currency", "in": "query", "description": "Document currency, exact code. Without it, one section per currency with a line in the range or a non-zero opening balance; with it, exactly that currency's section, zero when idle, and open_credits narrowed to it", "required": false, "schema": { "type": "string", "nullable": true, "enum": [ "USD", "VES", "USDT", "EUR", "DOP" ] } }, "ClientStatementFrom": { "name": "from", "in": "query", "description": "First day of the range on the company calendar, Y-m-d; every earlier movement folds into the opening balance", "required": true, "schema": { "type": "string", "format": "date" } }, "ClientStatementTo": { "name": "to", "in": "query", "description": "Last day of the range on the company calendar, Y-m-d, on or after from; it may be after today and no movement after it is read", "required": true, "schema": { "type": "string", "format": "date" } }, "ClientStatementCurrency": { "name": "currency", "in": "query", "description": "Document currency, exact code. Without it, one section per currency with a line in the range or a non-zero opening balance; with it, exactly that currency's section, zero when idle, and open_credits narrowed to it", "required": false, "schema": { "type": "string", "nullable": true, "enum": [ "USD", "VES", "USDT", "EUR", "DOP" ] } }, "ReceivablesAgingClient": { "name": "client_id", "in": "query", "description": "Existing client belonging to tenant; narrows debts and Customer Credit alike, so filtered totals no longer equal the ledger", "required": false, "schema": { "type": "string", "format": "uuid", "nullable": true } }, "ReceivablesAgingCurrency": { "name": "currency", "in": "query", "description": "Document currency, exact code; narrows debts and Customer Credit alike, so filtered totals no longer equal the ledger", "required": false, "schema": { "type": "string", "nullable": true, "enum": [ "USD", "VES", "USDT", "EUR", "DOP" ] } }, "ReceivablesAgingCenter": { "name": "accounting_center_id", "in": "query", "description": "Existing accounting center belonging to tenant, including inactive centers; narrows debts and Customer Credit alike, so filtered totals no longer equal the ledger", "required": false, "schema": { "type": "string", "format": "uuid", "nullable": true } } }, "securitySchemes": { "bearerAuth": { "type": "http", "description": "A Laravel Sanctum token sent as `Authorization: Bearer `. For integrations it is an API key created in the web application: bound to its owner and to one company, it acts with the owner's current permissions, and a read-only key answers 403 to any operation that changes data. The token is opaque (`|`), not a JWT. A missing, invalid, expired or revoked token answers 401; an API key used outside `/api/backoffice/{tenant}` for its own company answers 404.", "bearerFormat": "Sanctum", "scheme": "bearer" }, "cookieAuth": { "type": "apiKey", "description": "The browser session of the web application at https://erp.medine.tech: Laravel Sanctum stateful authentication carried by the HttpOnly, SameSite=Lax session cookie issued at sign-in and sent in the Cookie header (its name is deployment configuration). An operation that requires only this scheme is session-only: an API key or any other bearer token answers 403 \"This operation requires session authentication.\"", "name": "Cookie", "in": "header" }, "twilioSignature": { "type": "apiKey", "description": "Twilio's HMAC-SHA1 signature over the exact URL it was told to call plus the POST fields in sorted key order, base64-encoded and keyed with the account Auth Token. It is not a bearer credential a client mints per request, but the Auth Token IS the trust boundary: anyone holding it can produce a valid signature, so it is a shared secret to be rotated like one. A request without a valid signature is refused with 403.", "name": "X-Twilio-Signature", "in": "header" }, "assistantClientBasic": { "type": "http", "description": "A registered Asistente agent client authenticates with HTTP Basic: the client_id as the user name and its client secret as the password. The ERP stores only SHA-256 hashes of the secrets; a client without configured hashes is disabled and every request answers 401 invalid_client.", "scheme": "basic" }, "storefrontKeyBearer": { "type": "http", "description": "A Clave de Vitrina authenticates with HTTP Bearer: the one-time plaintext `mtsk_…` secret shown at issuance. The ERP stores only its sha256 digest; missing, malformed, unknown, revoked or channel-unusable keys answer the same 401 invalid_storefront_key.", "bearerFormat": "mtsk", "scheme": "bearer" }, "buyerSessionCookie": { "type": "apiKey", "name": "buyer_session", "in": "cookie" } } }, "tags": [ { "name": "Accounting / P&L Dashboard" }, { "name": "Assistant - Action Proposals", "description": "Assistant - Action Proposals" }, { "name": "Assistant - Attachments", "description": "Assistant - Attachments" }, { "name": "Assistant - Tokens", "description": "Assistant - Tokens" }, { "name": "Assistant - Usage", "description": "Assistant - Usage" }, { "name": "Assistant Usage", "description": "Assistant Usage" }, { "name": "Authentication", "description": "Authentication" }, { "name": "Auth - Companies", "description": "Auth - Companies" }, { "name": "Auth", "description": "Auth" }, { "name": "Auth - Users", "description": "Auth - Users" }, { "name": "Auth - User", "description": "Auth - User" }, { "name": "Backoffice - Accounting - Accounting Account Lookups", "description": "Backoffice - Accounting - Accounting Account Lookups" }, { "name": "Backoffice - Accounting - Accounting Accounts", "description": "Backoffice - Accounting - Accounting Accounts" }, { "name": "Backoffice - Accounting Accounts", "description": "Backoffice - Accounting Accounts" }, { "name": "Accounting Accounts", "description": "Accounting Accounts" }, { "name": "Backoffice - Accounting - Accounting Center Lookups", "description": "Backoffice - Accounting - Accounting Center Lookups" }, { "name": "Backoffice - Accounting - Accounting Centers", "description": "Backoffice - Accounting - Accounting Centers" }, { "name": "Backoffice - Accounting - Accounting Periods", "description": "Backoffice - Accounting - Accounting Periods" }, { "name": "Backoffice - Accounting - Exchange Rates", "description": "Backoffice - Accounting - Exchange Rates" }, { "name": "Backoffice - Accounting - Fx Revaluations", "description": "Backoffice - Accounting - Fx Revaluations" }, { "name": "Ledger Reports", "description": "Ledger Reports" }, { "name": "Backoffice - Accounting - Manual Entries", "description": "Backoffice - Accounting - Manual Entries" }, { "name": "Backoffice - Accounting - Month-End Closes", "description": "Backoffice - Accounting - Month-End Closes" }, { "name": "Backoffice - Accounting - Opening Balances", "description": "Backoffice - Accounting - Opening Balances" }, { "name": "Backoffice - Accounting - Payable Account Lookups", "description": "Backoffice - Accounting - Payable Account Lookups" }, { "name": "Backoffice - Accounting - Receivable Account Lookups", "description": "Backoffice - Accounting - Receivable Account Lookups" }, { "name": "Backoffice - Accounting - Settings - Inventory In Transit Accounts", "description": "Backoffice - Accounting - Settings - Inventory In Transit Accounts" }, { "name": "Backoffice - Accounting - Settings - Payable Accountings", "description": "Backoffice - Accounting - Settings - Payable Accountings" }, { "name": "Backoffice - Accounting - Settings - Posting Accounts", "description": "Backoffice - Accounting - Settings - Posting Accounts" }, { "name": "Backoffice - Accounting - Settings - Receivable Accountings", "description": "Backoffice - Accounting - Settings - Receivable Accountings" }, { "name": "Backoffice - Receivable Accounts", "description": "Backoffice - Receivable Accounts" }, { "name": "Backoffice - Accounting - Settings - Taxes", "description": "Backoffice - Accounting - Settings - Taxes" }, { "name": "Backoffice - Accounting - Settings - Vat Input Accounts", "description": "Backoffice - Accounting - Settings - Vat Input Accounts" }, { "name": "Backoffice - Accounting - Tax Lookups", "description": "Backoffice - Accounting - Tax Lookups" }, { "name": "Accounting Transactions", "description": "Accounting Transactions" }, { "name": "Backoffice - Fiscal - Tax Declarations", "description": "Backoffice - Fiscal - Tax Declarations" }, { "name": "Backoffice - Collaboration - Attachments", "description": "Backoffice - Collaboration - Attachments" }, { "name": "Backoffice - Collaboration - Comments", "description": "Backoffice - Collaboration - Comments" }, { "name": "Backoffice - Inventory Items", "description": "Backoffice - Inventory Items" }, { "name": "Backoffice - Collaboration - Followers", "description": "Backoffice - Collaboration - Followers" }, { "name": "Backoffice - Collaboration - Label Assignments", "description": "Backoffice - Collaboration - Label Assignments" }, { "name": "Backoffice - Collaboration - Labels", "description": "Backoffice - Collaboration - Labels" }, { "name": "Backoffice - Collaboration", "description": "Backoffice - Collaboration" }, { "name": "Backoffice - Inbox", "description": "Backoffice - Inbox" }, { "name": "Notification preferences", "description": "Notification preferences" }, { "name": "Backoffice - Companies", "description": "Backoffice - Companies" }, { "name": "Backoffice - Companies - Book Currencies", "description": "Backoffice - Companies - Book Currencies" }, { "name": "Backoffice - Companies - Capabilities", "description": "Backoffice - Companies - Capabilities" }, { "name": "Companies", "description": "Companies" }, { "name": "Subscriptions", "description": "Subscriptions" }, { "name": "Company user defaults", "description": "Company user defaults" }, { "name": "Backoffice - Company User Lookups", "description": "Backoffice - Company User Lookups" }, { "name": "Backoffice - First Companies", "description": "Backoffice - First Companies" }, { "name": "Backoffice - Fiscal - Fiscal Periods", "description": "Backoffice - Fiscal - Fiscal Periods" }, { "name": "Backoffice - Fiscal Rules", "description": "Backoffice - Fiscal Rules" }, { "name": "Backoffice - Fiscal - ISLR Concept Lookups", "description": "Backoffice - Fiscal - ISLR Concept Lookups" }, { "name": "Backoffice - Fiscal Withholdings", "description": "Backoffice - Fiscal Withholdings" }, { "name": "Backoffice - Fiscal - Portal Exports", "description": "Backoffice - Fiscal - Portal Exports" }, { "name": "Backoffice - Fiscal - Purchase Book", "description": "Backoffice - Fiscal - Purchase Book" }, { "name": "Backoffice - Fiscal - Sales Book", "description": "Backoffice - Fiscal - Sales Book" }, { "name": "Backoffice - Fiscal - Tax Obligations", "description": "Backoffice - Fiscal - Tax Obligations" }, { "name": "Backoffice - Fiscal - VAT Workpapers", "description": "Backoffice - Fiscal - VAT Workpapers" }, { "name": "Backoffice - Fiscal - Withholding Workpapers", "description": "Backoffice - Fiscal - Withholding Workpapers" }, { "name": "Backoffice - Getting Started", "description": "Backoffice - Getting Started" }, { "name": "History", "description": "History" }, { "name": "Backoffice - Inventory Adjustments", "description": "Backoffice - Inventory Adjustments" }, { "name": "Backoffice - Inventory - Book Currencies", "description": "Backoffice - Inventory - Book Currencies" }, { "name": "Backoffice - Inventory - Counter Catalog", "description": "Backoffice - Inventory - Counter Catalog" }, { "name": "Backoffice - Inventory Dispatches", "description": "Backoffice - Inventory Dispatches" }, { "name": "Backoffice - Inventory - Dispatches", "description": "Backoffice - Inventory - Dispatches" }, { "name": "Backoffice - Inventory - Entries", "description": "Backoffice - Inventory - Entries" }, { "name": "Backoffice - Inventory Entries", "description": "Backoffice - Inventory Entries" }, { "name": "Backoffice - Inventory - Item Category Lookups", "description": "Backoffice - Inventory - Item Category Lookups" }, { "name": "Backoffice - Inventory Item Locations", "description": "Backoffice - Inventory Item Locations" }, { "name": "Backoffice - Inventory - Item Lookups", "description": "Backoffice - Inventory - Item Lookups" }, { "name": "Backoffice - Inventory - Item Search", "description": "Backoffice - Inventory - Item Search" }, { "name": "Backoffice - Inventory - Location Lookups", "description": "Backoffice - Inventory - Location Lookups" }, { "name": "Backoffice - Inventory Locations", "description": "Backoffice - Inventory Locations" }, { "name": "Backoffice - Inventory - Settings - Categories", "description": "Backoffice - Inventory - Settings - Categories" }, { "name": "Backoffice - Inventory - Settings - Units", "description": "Backoffice - Inventory - Settings - Units" }, { "name": "Backoffice - Inventory - Transfers", "description": "Backoffice - Inventory - Transfers" }, { "name": "Backoffice - Inventory Transformations", "description": "Backoffice - Inventory Transformations" }, { "name": "Transformations", "description": "Transformations" }, { "name": "Backoffice - Inventory - Unit Lookups", "description": "Backoffice - Inventory - Unit Lookups" }, { "name": "Backoffice - Inventory - Variant Groups", "description": "Backoffice - Inventory - Variant Groups" }, { "name": "Backoffice - Menu - Contexts", "description": "Backoffice - Menu - Contexts" }, { "name": "Backoffice - Menu - Modules", "description": "Backoffice - Menu - Modules" }, { "name": "Backoffice - Purchase Contract Activations", "description": "Backoffice - Purchase Contract Activations" }, { "name": "Backoffice - Purchase Contract Addenda", "description": "Backoffice - Purchase Contract Addenda" }, { "name": "Backoffice - Purchases - ContractAddenda", "description": "Backoffice - Purchases - ContractAddenda" }, { "name": "Backoffice - Purchase Contract Charges", "description": "Backoffice - Purchase Contract Charges" }, { "name": "Backoffice - Purchase Contract Deactivations", "description": "Backoffice - Purchase Contract Deactivations" }, { "name": "Backoffice - Purchases - ContractDeactivations", "description": "Backoffice - Purchases - ContractDeactivations" }, { "name": "Backoffice - Purchase Contracts", "description": "Backoffice - Purchase Contracts" }, { "name": "Backoffice - Purchases Credit Applications", "description": "Backoffice - Purchases Credit Applications" }, { "name": "Backoffice - Purchases Credit Notes", "description": "Backoffice - Purchases Credit Notes" }, { "name": "Backoffice - Purchases - Supplier Notes", "description": "Backoffice - Purchases - Supplier Notes" }, { "name": "Backoffice - Purchases Debit Notes", "description": "Backoffice - Purchases Debit Notes" }, { "name": "Backoffice - Orders", "description": "Backoffice - Orders" }, { "name": "Purchases Payables", "description": "Purchases Payables" }, { "name": "Backoffice - Payment Views", "description": "Backoffice - Payment Views" }, { "name": "Backoffice - Payments", "description": "Backoffice - Payments" }, { "name": "Backoffice - Purchases Payments", "description": "Backoffice - Purchases Payments" }, { "name": "Backoffice - Purchases - Provider Lookups", "description": "Backoffice - Purchases - Provider Lookups" }, { "name": "Backoffice - Purchases - Providers", "description": "Backoffice - Purchases - Providers" }, { "name": "Backoffice - Providers", "description": "Backoffice - Providers" }, { "name": "Backoffice - Purchases - Activation Lookups", "description": "Backoffice - Purchases - Activation Lookups" }, { "name": "Backoffice - Purchases - Purchase Contract Lookups", "description": "Backoffice - Purchases - Purchase Contract Lookups" }, { "name": "Backoffice - Purchases - Invoice Lookups", "description": "Backoffice - Purchases - Invoice Lookups" }, { "name": "Backoffice - Purchase Invoice Views", "description": "Backoffice - Purchase Invoice Views" }, { "name": "Backoffice - Purchase Orders", "description": "Backoffice - Purchase Orders" }, { "name": "Backoffice - Purchases Invoices", "description": "Backoffice - Purchases Invoices" }, { "name": "Backoffice - Sales - Client Lookups", "description": "Backoffice - Sales - Client Lookups" }, { "name": "Backoffice - Sales - Clients", "description": "Backoffice - Sales - Clients" }, { "name": "Backoffice - Clients", "description": "Backoffice - Clients" }, { "name": "Backoffice - Collections", "description": "Backoffice - Collections" }, { "name": "Backoffice - Sales Collections", "description": "Backoffice - Sales Collections" }, { "name": "Backoffice - Sales - Contacts", "description": "Backoffice - Sales - Contacts" }, { "name": "Backoffice - Sales - ContractActivation Lookups", "description": "Backoffice - Sales - ContractActivation Lookups" }, { "name": "Backoffice - Contract Activations", "description": "Backoffice - Contract Activations" }, { "name": "Backoffice - Sales - ContractActivations", "description": "Backoffice - Sales - ContractActivations" }, { "name": "Backoffice - Contract Charges", "description": "Backoffice - Contract Charges" }, { "name": "Backoffice - Sales - ContractCharges", "description": "Backoffice - Sales - ContractCharges" }, { "name": "Backoffice - Contract Deactivations", "description": "Backoffice - Contract Deactivations" }, { "name": "Backoffice - Sales - ContractDeactivations", "description": "Backoffice - Sales - ContractDeactivations" }, { "name": "Backoffice - Sales - Contract Lookups", "description": "Backoffice - Sales - Contract Lookups" }, { "name": "Backoffice - Contracts", "description": "Backoffice - Contracts" }, { "name": "Backoffice - Sales Contracts", "description": "Backoffice - Sales Contracts" }, { "name": "Backoffice - Sales - Counter Sales", "description": "Backoffice - Sales - Counter Sales" }, { "name": "Backoffice - Sales Credit Applications", "description": "Backoffice - Sales Credit Applications" }, { "name": "Backoffice - Sales Credit Notes", "description": "Backoffice - Sales Credit Notes" }, { "name": "Backoffice - Sales Debit Notes", "description": "Backoffice - Sales Debit Notes" }, { "name": "Backoffice - Sales - SalesOrders", "description": "Backoffice - Sales - SalesOrders" }, { "name": "Backoffice - Sales - Opportunities", "description": "Backoffice - Sales - Opportunities" }, { "name": "Backoffice - Sales - Owner Step-Up Authorizations", "description": "Backoffice - Sales - Owner Step-Up Authorizations" }, { "name": "Backoffice - Sales - POS Sessions", "description": "Backoffice - Sales - POS Sessions" }, { "name": "Backoffice - Sales - Potential Customers", "description": "Backoffice - Sales - Potential Customers" }, { "name": "Backoffice - Sales - Potential Customer Interactions", "description": "Backoffice - Sales - Potential Customer Interactions" }, { "name": "Backoffice - Sales - Price List Lookups", "description": "Backoffice - Sales - Price List Lookups" }, { "name": "Backoffice - Sales - Price Lists", "description": "Backoffice - Sales - Price Lists" }, { "name": "Sales Receivables", "description": "Sales Receivables" }, { "name": "Backoffice - Sales - Storefront Keys", "description": "Backoffice - Sales - Storefront Keys" }, { "name": "Backoffice - Sales - Sales Channels", "description": "Backoffice - Sales - Sales Channels" }, { "name": "Backoffice - Sales - Invoice Lookups", "description": "Backoffice - Sales - Invoice Lookups" }, { "name": "Sales", "description": "Sales" }, { "name": "Backoffice - Sales Invoices", "description": "Backoffice - Sales Invoices" }, { "name": "Backoffice - Sales - SalesInvoices", "description": "Backoffice - Sales - SalesInvoices" }, { "name": "Backoffice - Sales - Sales Notes", "description": "Backoffice - Sales - Sales Notes" }, { "name": "Backoffice - Sales Orders", "description": "Backoffice - Sales Orders" }, { "name": "Sales Orders", "description": "Sales Orders" }, { "name": "Backoffice - Sales Quotes", "description": "Backoffice - Sales Quotes" }, { "name": "Backoffice - Sales - SalesQuotes", "description": "Backoffice - Sales - SalesQuotes" }, { "name": "Backoffice - Sales - Salesperson Lookups", "description": "Backoffice - Sales - Salesperson Lookups" }, { "name": "Backoffice - Sales - Web Orders", "description": "Backoffice - Sales - Web Orders" }, { "name": "Backoffice - Security - API Keys", "description": "Backoffice - Security - API Keys" }, { "name": "Backoffice - Security - Contexts", "description": "Backoffice - Security - Contexts" }, { "name": "Backoffice - Security - Modules", "description": "Backoffice - Security - Modules" }, { "name": "Backoffice - Security - Permissions", "description": "Backoffice - Security - Permissions" }, { "name": "Backoffice - Security - Role Permissions", "description": "Backoffice - Security - Role Permissions" }, { "name": "Backoffice - Security - Role Templates", "description": "Backoffice - Security - Role Templates" }, { "name": "Backoffice - Security - Roles", "description": "Backoffice - Security - Roles" }, { "name": "Backoffice - Treasury - Bank Reconciliations", "description": "Backoffice - Treasury - Bank Reconciliations" }, { "name": "Backoffice - Treasury - Bank Statement Import Profiles", "description": "Backoffice - Treasury - Bank Statement Import Profiles" }, { "name": "Backoffice - Treasury - Bank Statement Imports", "description": "Backoffice - Treasury - Bank Statement Imports" }, { "name": "Backoffice - Treasury - Bank Statement Lines", "description": "Backoffice - Treasury - Bank Statement Lines" }, { "name": "Backoffice - Treasury - Cash Movements", "description": "Backoffice - Treasury - Cash Movements" }, { "name": "Backoffice - Treasury - Cash Registers", "description": "Backoffice - Treasury - Cash Registers" }, { "name": "Backoffice - Treasury - Cash Shifts", "description": "Backoffice - Treasury - Cash Shifts" }, { "name": "Backoffice - Treasury - Payment Instrument Lookups", "description": "Backoffice - Treasury - Payment Instrument Lookups" }, { "name": "Backoffice - Treasury - Payment Instruments", "description": "Backoffice - Treasury - Payment Instruments" }, { "name": "Backoffice - Treasury - Reconciliation Matches", "description": "Backoffice - Treasury - Reconciliation Matches" }, { "name": "Backoffice - Treasury - Treasury Account Lookups", "description": "Backoffice - Treasury - Treasury Account Lookups" }, { "name": "Backoffice - Treasury - Treasury Accounts", "description": "Backoffice - Treasury - Treasury Accounts" }, { "name": "Backoffice - Treasury - Treasury Transfers", "description": "Backoffice - Treasury - Treasury Transfers" }, { "name": "Backoffice - Users", "description": "Backoffice - Users" }, { "name": "Users", "description": "Users" }, { "name": "MoneyManager - Accounts", "description": "MoneyManager - Accounts" }, { "name": "MoneyManager - Categories", "description": "MoneyManager - Categories" }, { "name": "MoneyManager - Household", "description": "MoneyManager - Household" }, { "name": "MoneyManager - RecurrenceRules", "description": "MoneyManager - RecurrenceRules" }, { "name": "MoneyManager - Transactions", "description": "MoneyManager - Transactions" }, { "name": "PhoneVerification - Verifications", "description": "PhoneVerification - Verifications" }, { "name": "PhoneVerification - Webhooks", "description": "PhoneVerification - Webhooks" }, { "name": "Storefront", "description": "Storefront" } ], "externalDocs": { "description": "Guía para integradores", "url": "https://medine.tech/desarrolladores" } }