{ "openapi": "3.1.1", "info": { "title": "Devkora Facturación API", "description": "API pública para emitir y consultar comprobantes electrónicos ante SUNAT.", "version": "v1" }, "paths": { "/v1/companies": { "get": { "tags": [ "Companies" ], "summary": "Lista las empresas del tenant con sus series del ambiente de la clave", "description": "Requiere el scope `companies:read`.", "operationId": "ListIntegrationCompanies", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageOfIntegrationCompanyDto" } } } }, "400": { "description": "Bad Request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unprocessable Entity", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service Unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/documents": { "post": { "tags": [ "Documents" ], "summary": "Emite una boleta o una factura", "description": "Requiere el scope `documents:write`.", "operationId": "IssueDocument", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "Identifica la operación para reintentarla sin duplicarla durante 24 horas; se recomienda un UUID.", "required": true, "schema": { "maxLength": 128, "pattern": "^[A-Za-z0-9._:-]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IssueDocumentCommand" } } }, "required": true }, "responses": { "201": { "description": "Created", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentDto" } } } }, "400": { "description": "Bad Request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload Too Large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "415": { "description": "Unsupported Media Type", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unprocessable Entity", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service Unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "get": { "tags": [ "Documents" ], "summary": "Lista los documentos del ambiente de la clave", "description": "Requiere el scope `documents:read`.", "operationId": "ListDocuments", "parameters": [ { "name": "company_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "type", "in": "query", "schema": { "enum": [ "factura", "boleta", "nota_credito" ], "type": "string" } }, { "name": "status", "in": "query", "schema": { "enum": [ "issued", "void_requested", "voided", "expired" ], "type": "string" } }, { "name": "sunat_status", "in": "query", "schema": { "enum": [ "pending", "submitted", "accepted", "accepted_with_observations", "rejected", "deadline_missed" ], "type": "string" } }, { "name": "series", "in": "query", "schema": { "type": "string" } }, { "name": "issue_date_from", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "issue_date_to", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "external_id", "in": "query", "schema": { "type": "string" } }, { "name": "created_from", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "created_to", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "updated_from", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "updated_to", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "order", "in": "query", "schema": { "enum": [ "updated_at" ], "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageOfDocumentDto" } } } }, "400": { "description": "Bad Request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unprocessable Entity", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service Unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/documents/{id}/credit-notes": { "post": { "tags": [ "Documents" ], "summary": "Emite una nota de crédito sobre un documento aceptado", "description": "Requiere el scope `documents:write`.", "operationId": "IssueCreditNote", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "description": "Identifica la operación para reintentarla sin duplicarla durante 24 horas; se recomienda un UUID.", "required": true, "schema": { "maxLength": 128, "pattern": "^[A-Za-z0-9._:-]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IssueCreditNoteCommand" } } }, "required": true }, "responses": { "201": { "description": "Created", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentDto" } } } }, "400": { "description": "Bad Request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload Too Large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "415": { "description": "Unsupported Media Type", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unprocessable Entity", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service Unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/documents/{id}": { "get": { "tags": [ "Documents" ], "summary": "Lee un documento", "description": "Requiere el scope `documents:read`.", "operationId": "GetDocument", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentDto" } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service Unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/documents/{id}/xml": { "get": { "tags": [ "Documents" ], "summary": "Descarga el XML firmado", "description": "Requiere el scope `documents:read`.", "operationId": "GetDocumentXml", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/xml": { "schema": { "$ref": "#/components/schemas/Stream" } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service Unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/documents/{id}/pdf": { "get": { "tags": [ "Documents" ], "summary": "Descarga el PDF", "description": "Requiere el scope `documents:read`.", "operationId": "GetDocumentPdf", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "format", "in": "query", "schema": { "enum": [ "a4", "ticket" ], "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/pdf": { "schema": { "$ref": "#/components/schemas/Stream" } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unprocessable Entity", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service Unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/documents/{id}/cdr": { "get": { "tags": [ "Documents" ], "summary": "Descarga el CDR de SUNAT", "description": "Requiere el scope `documents:read`.", "operationId": "GetDocumentCdr", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/zip": { "schema": { "$ref": "#/components/schemas/Stream" } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service Unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/documents/{id}/void": { "post": { "tags": [ "Documents" ], "summary": "Solicita la baja de un documento aceptado", "description": "Requiere el scope `documents:write`.", "operationId": "RequestDocumentVoid", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "description": "Identifica la operación para reintentarla sin duplicarla durante 24 horas; se recomienda un UUID.", "required": true, "schema": { "maxLength": 128, "pattern": "^[A-Za-z0-9._:-]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestVoidCommand" } } }, "required": true }, "responses": { "202": { "description": "Accepted", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentDto" } } } }, "400": { "description": "Bad Request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload Too Large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "415": { "description": "Unsupported Media Type", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unprocessable Entity", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service Unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } } }, "components": { "schemas": { "CompanyStatus": { "enum": [ "draft", "ready", "suspended" ] }, "CreditNoteReason": { "enum": [ "anulacion_operacion", "anulacion_error_ruc", "correccion_descripcion", "descuento_global", "descuento_item", "devolucion_total", "devolucion_item", "bonificacion", "disminucion_valor", "otros" ] }, "CustomerDocumentType": { "enum": [ "dni", "ruc", "ce", "pasaporte", "otros", "none" ] }, "DeliveryStatus": { "enum": [ "none", "pending", "delivered", "failed" ] }, "DocumentCreditNoteDto": { "required": [ "reason_code", "reason" ], "type": "object", "properties": { "reason_code": { "$ref": "#/components/schemas/CreditNoteReason" }, "reason": { "type": "string" } } }, "DocumentCustomerDto": { "required": [ "document_type", "document_number", "name", "address", "email" ], "type": "object", "properties": { "document_type": { "$ref": "#/components/schemas/CustomerDocumentType" }, "document_number": { "type": [ "null", "string" ] }, "name": { "type": [ "null", "string" ] }, "address": { "type": [ "null", "string" ] }, "email": { "type": [ "null", "string" ] } } }, "DocumentCustomerInput": { "required": [ "document_type" ], "type": "object", "properties": { "document_type": { "enum": [ "dni", "ruc", "ce", "pasaporte", "otros", "none" ], "type": "string" }, "document_number": { "type": [ "null", "string" ] }, "name": { "type": [ "null", "string" ] }, "address": { "type": [ "null", "string" ] }, "email": { "type": [ "null", "string" ] } } }, "DocumentDto": { "required": [ "id", "object", "environment", "company_id", "type", "series", "number", "full_number", "issue_date", "currency", "customer", "totals", "status", "sunat_status", "delivery_status", "sunat", "hash", "qr_text", "links", "affected_document_id", "credit_note", "external_id", "replaces_document_id", "metadata", "created_at", "updated_at" ], "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "object": { "type": "string" }, "environment": { "$ref": "#/components/schemas/FiscalEnvironment" }, "company_id": { "type": "string", "format": "uuid" }, "type": { "$ref": "#/components/schemas/DocumentType" }, "series": { "type": "string" }, "number": { "type": "integer", "format": "int64" }, "full_number": { "type": "string" }, "issue_date": { "type": "string", "format": "date" }, "currency": { "type": "string" }, "customer": { "$ref": "#/components/schemas/DocumentCustomerDto" }, "items": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/DocumentItemDto" } }, "totals": { "$ref": "#/components/schemas/DocumentTotalsDto" }, "status": { "$ref": "#/components/schemas/DocumentStatus" }, "sunat_status": { "$ref": "#/components/schemas/SunatStatus" }, "delivery_status": { "$ref": "#/components/schemas/DeliveryStatus" }, "sunat": { "$ref": "#/components/schemas/DocumentSunatDto" }, "hash": { "type": "string" }, "qr_text": { "type": "string" }, "qr_image": { "type": [ "null", "string" ] }, "links": { "$ref": "#/components/schemas/DocumentLinksDto" }, "affected_document_id": { "type": [ "null", "string" ], "format": "uuid" }, "credit_note": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DocumentCreditNoteDto" } ] }, "external_id": { "type": [ "null", "string" ] }, "replaces_document_id": { "type": [ "null", "string" ], "format": "uuid" }, "metadata": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/JsonElement" } ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "DocumentItemDto": { "required": [ "line_number", "product_code", "description", "quantity", "unit", "unit_price", "unit_value", "tax_affectation", "igv_rate", "line_value", "igv_amount", "line_total" ], "type": "object", "properties": { "line_number": { "type": "integer", "format": "int32" }, "product_code": { "type": [ "null", "string" ] }, "description": { "type": "string" }, "quantity": { "type": "number" }, "unit": { "type": "string" }, "unit_price": { "type": "number" }, "unit_value": { "type": "number" }, "tax_affectation": { "$ref": "#/components/schemas/ItemTaxAffectation" }, "igv_rate": { "type": "number" }, "line_value": { "type": "number" }, "igv_amount": { "type": "number" }, "line_total": { "type": "number" } } }, "DocumentItemInput": { "required": [ "description", "quantity" ], "type": "object", "properties": { "description": { "type": "string" }, "quantity": { "type": "number" }, "unit": { "type": [ "null", "string" ] }, "unit_price": { "type": [ "null", "number" ] }, "unit_value": { "type": [ "null", "number" ] }, "tax_affectation": { "enum": [ "gravado", "exonerado", "inafecto" ], "type": [ "null", "string" ] }, "product_code": { "type": [ "null", "string" ] } } }, "DocumentLinksDto": { "required": [ "pdf", "xml", "cdr" ], "type": "object", "properties": { "pdf": { "type": [ "null", "string" ] }, "xml": { "type": [ "null", "string" ] }, "cdr": { "type": [ "null", "string" ] } } }, "DocumentStatus": { "enum": [ "issued", "void_requested", "voided", "expired" ] }, "DocumentSunatDto": { "required": [ "response_code", "description", "notes", "deadline_at", "submitted_at", "accepted_at", "reconciliation_required" ], "type": "object", "properties": { "response_code": { "type": [ "null", "string" ] }, "description": { "type": [ "null", "string" ] }, "notes": { "type": "array", "items": { "type": "string" } }, "deadline_at": { "type": "string", "format": "date-time" }, "submitted_at": { "type": [ "null", "string" ], "format": "date-time" }, "accepted_at": { "type": [ "null", "string" ], "format": "date-time" }, "reconciliation_required": { "type": "boolean" } } }, "DocumentTotalsDto": { "required": [ "taxable", "exempt", "unaffected", "discount", "igv", "total", "amount_in_words" ], "type": "object", "properties": { "taxable": { "type": "number" }, "exempt": { "type": "number" }, "unaffected": { "type": "number" }, "discount": { "type": "number" }, "igv": { "type": "number" }, "total": { "type": "number" }, "amount_in_words": { "type": "string" } } }, "DocumentType": { "enum": [ "factura", "boleta", "nota_credito" ] }, "EnvironmentsReadyDto": { "required": [ "test", "live" ], "type": "object", "properties": { "test": { "type": "boolean" }, "live": { "type": "boolean" } } }, "ErrorBody": { "required": [ "type", "code", "message", "request_id" ], "type": "object", "properties": { "type": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": [ "null", "string" ] }, "request_id": { "type": "string" }, "document_id": { "type": [ "null", "string" ], "format": "uuid" } } }, "ErrorItem": { "required": [ "code", "message" ], "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": [ "null", "string" ] } } }, "ErrorResponse": { "required": [ "error" ], "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorBody" }, "errors": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/ErrorItem" } } } }, "FiscalEnvironment": { "enum": [ "test", "live" ] }, "IntegrationCompanyDto": { "required": [ "id", "ruc", "legal_name", "trade_name", "status", "environments_ready", "series" ], "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "ruc": { "type": "string" }, "legal_name": { "type": "string" }, "trade_name": { "type": [ "null", "string" ] }, "status": { "$ref": "#/components/schemas/CompanyStatus" }, "environments_ready": { "$ref": "#/components/schemas/EnvironmentsReadyDto" }, "series": { "type": "array", "items": { "$ref": "#/components/schemas/IntegrationSeriesDto" } } } }, "IntegrationSeriesDto": { "required": [ "id", "establishment_id", "environment", "document_type", "code", "is_default" ], "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "establishment_id": { "type": "string", "format": "uuid" }, "environment": { "$ref": "#/components/schemas/FiscalEnvironment" }, "document_type": { "$ref": "#/components/schemas/SeriesDocumentType" }, "code": { "type": "string" }, "is_default": { "type": "boolean" } } }, "IssueCreditNoteCommand": { "required": [ "reason", "reason_code" ], "type": "object", "properties": { "reason_code": { "enum": [ "anulacion_operacion", "anulacion_error_ruc", "correccion_descripcion", "descuento_global", "descuento_item", "devolucion_total", "devolucion_item", "bonificacion", "disminucion_valor", "otros" ], "type": "string" }, "reason": { "type": "string" }, "items": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/DocumentItemInput" } }, "series": { "type": [ "null", "string" ] }, "issue_date": { "type": [ "null", "string" ], "format": "date" }, "notes": { "type": [ "null", "string" ] }, "metadata": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/JsonElement" } ] }, "external_id": { "type": [ "null", "string" ] } } }, "IssueDocumentCommand": { "required": [ "items", "type" ], "type": "object", "properties": { "type": { "enum": [ "factura", "boleta" ], "type": "string" }, "company_id": { "type": [ "null", "string" ], "format": "uuid" }, "establishment_code": { "type": [ "null", "string" ] }, "series": { "type": [ "null", "string" ] }, "issue_date": { "type": [ "null", "string" ], "format": "date" }, "currency": { "enum": [ "PEN" ], "type": [ "null", "string" ] }, "customer": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DocumentCustomerInput" } ] }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentItemInput" } }, "notes": { "type": [ "null", "string" ] }, "payment_terms": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaymentTermsInput" } ] }, "metadata": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/JsonElement" } ] }, "external_id": { "type": [ "null", "string" ] }, "replaces_document_id": { "type": [ "null", "string" ], "format": "uuid" } } }, "ItemTaxAffectation": { "enum": [ "gravado", "exonerado", "inafecto" ] }, "JsonElement": { "type": "object" }, "PageOfDocumentDto": { "required": [ "data", "next_cursor" ], "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentDto" } }, "next_cursor": { "type": [ "null", "string" ] } } }, "PageOfIntegrationCompanyDto": { "required": [ "data", "next_cursor" ], "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/IntegrationCompanyDto" } }, "next_cursor": { "type": [ "null", "string" ] } } }, "PaymentTermsInput": { "required": [ "type" ], "type": "object", "properties": { "type": { "enum": [ "contado" ], "type": "string" } } }, "RequestVoidCommand": { "required": [ "reason" ], "type": "object", "properties": { "reason": { "type": "string" } } }, "SeriesDocumentType": { "enum": [ "factura", "boleta", "nota_credito" ] }, "Stream": { "type": "string", "format": "binary" }, "SunatStatus": { "enum": [ "pending", "submitted", "accepted", "accepted_with_observations", "rejected", "deadline_missed" ] } }, "headers": { "X-Request-Id": { "description": "El del cliente si tiene de 1 a 128 caracteres `[A-Za-z0-9._-]`; si no, uno generado. Es el `request_id` de los errores.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Solicitudes admitidas en la ventana de un minuto, de la clave o de la IP.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Solicitudes que quedan en la ventana.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Segundos hasta la ventana siguiente.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Segundos que conviene esperar antes de reintentar.", "schema": { "type": "integer" } }, "Idempotent-Replayed": { "description": "`true` cuando la respuesta es la guardada de una solicitud anterior con la misma `Idempotency-Key`.", "schema": { "type": "string" } } }, "securitySchemes": { "api_key": { "type": "http", "description": "API key en `Authorization: Bearer`. El prefijo `dk_test_` o `dk_live_` elige el ambiente.", "scheme": "bearer" } } }, "security": [ { "api_key": [ ] } ], "tags": [ { "name": "Companies" }, { "name": "Documents" } ] }