{ "openapi": "3.1.1", "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema", "info": { "title": "SIPAgentAI — API de facturación electrónica (Ecuador)", "version": "1.0.0", "summary": "Creación de los seis comprobantes electrónicos del SRI Ecuador y emisión al SRI.", "description": "API REST del ERP SIPAgentAI para crear comprobantes electrónicos autorizados por el\nSRI de Ecuador y transmitirlos.\n\n**Autenticación:** cookie de sesión de Better Auth\n(`__Secure-better-auth.session_token` en producción), la\nmisma de la aplicación web. Estos endpoints NO aceptan la credencial `sipmcp_...` del\nservidor MCP. Si lo que buscás es automatizar sin navegador, el camino es el servidor\nMCP en `https://app.sipagentai.com/api/mcp` — ver https://app.sipagentai.com/docs/mcp.\n\n**Multi-empresa:** la empresa sobre la que operan estos endpoints se deriva de la\nsesión. No es un parámetro.\n\n**Alcance:** este documento cubre los seis endpoints de creación y el de emisión al\nSRI. Los `GET` de listado no están descritos porque sus esquemas de query no están\nexportados y transcribirlos a mano abriría la puerta a que el documento y el código\nse desincronicen.\n\n**Cómo se genera:** los cuerpos de petición salen de `z.toJSONSchema()` sobre los\nmismos esquemas Zod que validan cada petición en producción. No hay ningún campo\nescrito a mano.\n\n**Antes de emitir:** desde el 1-ene-2026 la transmisión al SRI es inmediata, y las\nfacturas a consumidor final (`9999999999999`) no se pueden anular ni corregir con\nnota de crédito una vez transmitidas (Resolución NAC-DGERCGC25-00000017, vigente\ndesde el 1-ago-2025). Es normativa externa: verificá el texto vigente en sri.gob.ec\nantes de tomar una decisión basada en un plazo.", "contact": { "name": "SIPAgentAI", "url": "https://app.sipagentai.com/docs/mcp" } }, "servers": [ { "url": "https://app.sipagentai.com", "description": "Producción" } ], "tags": [ { "name": "Facturación", "description": "Creación de comprobantes electrónicos en estado BORRADOR." }, { "name": "SRI", "description": "Firma, transmisión y autorización ante el SRI." } ], "security": [ { "sesionWeb": [] } ], "paths": { "/api/erp/facturacion/factura": { "post": { "tags": [ "Facturación" ], "operationId": "crearFactura", "summary": "Crear una factura (comprobante 01)", "description": "Crea una factura de venta en estado BORRADOR: asigna secuencial, calcula impuestos, arma el XML, descuenta el stock de la bodega indicada y genera la cuenta por cobrar. NO la firma ni la envía al SRI: para eso está POST /api/erp/sri/emitir. El SRI no permite facturar más de $50.00 con IVA a consumidor final (9999999999999).\n\nPermiso requerido: `ERP_FACTURACION_FACTURA / crear`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacturaInput" } } } }, "responses": { "201": { "description": "Comprobante recién creado, en BORRADOR y sin firmar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComprobanteCreado" } } } }, "400": { "description": "El cuerpo no pasó la validación, o una regla de negocio lo rechazó.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No hay sesión activa.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "La sesión no tiene el permiso que exige el endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Alguna de las entidades referenciadas (cliente, proveedor, punto de emisión, comprobante) no existe en esta empresa.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado actual del documento.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Falta configuración de la empresa (certificado P12, establecimiento, punto de emisión).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Se superó el límite de peticiones.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/erp/facturacion/nota-credito": { "post": { "tags": [ "Facturación" ], "operationId": "crearNotaCredito", "summary": "Crear una nota de crédito (comprobante 04)", "description": "Crea una nota de crédito sobre una factura ya emitida: devolución, descuento posterior, corrección a la baja o anulación comercial. Puede ser total o parcial. Las facturas a consumidor final no admiten nota de crédito desde 2026.\n\nPermiso requerido: `ERP_FACTURACION_NC / crear`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotaCreditoInput" } } } }, "responses": { "201": { "description": "Nota de crédito recién creada, en BORRADOR y sin firmar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotaCreditoCreada" } } } }, "400": { "description": "El cuerpo no pasó la validación, o una regla de negocio lo rechazó.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No hay sesión activa.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "La sesión no tiene el permiso que exige el endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Alguna de las entidades referenciadas (cliente, proveedor, punto de emisión, comprobante) no existe en esta empresa.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado actual del documento.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Falta configuración de la empresa (certificado P12, establecimiento, punto de emisión).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Se superó el límite de peticiones.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/erp/facturacion/nota-debito": { "post": { "tags": [ "Facturación" ], "operationId": "crearNotaDebito", "summary": "Crear una nota de débito (comprobante 05)", "description": "Crea una nota de débito por un cargo adicional posterior a una factura. No lleva detalles sino motivos (razón y valor), y todos comparten un único grupo de impuesto definido a nivel de documento.\n\nPermiso requerido: `ERP_FACTURACION_ND / crear`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotaDebitoInput" } } } }, "responses": { "201": { "description": "Nota de débito recién creada, en BORRADOR y sin firmar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComprobanteCreado" } } } }, "400": { "description": "El cuerpo no pasó la validación, o una regla de negocio lo rechazó.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No hay sesión activa.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "La sesión no tiene el permiso que exige el endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Alguna de las entidades referenciadas (cliente, proveedor, punto de emisión, comprobante) no existe en esta empresa.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado actual del documento.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Falta configuración de la empresa (certificado P12, establecimiento, punto de emisión).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Se superó el límite de peticiones.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/erp/facturacion/retencion": { "post": { "tags": [ "Facturación" ], "operationId": "crearRetencion", "summary": "Crear un comprobante de retención (comprobante 07)", "description": "Crea un comprobante de retención de IVA o de impuesto a la renta sobre una compra. Junto con la liquidación de compra, es uno de los dos documentos que se emiten a un PROVEEDOR y no a un cliente: todo gira alrededor de proveedorId y del documento de sustento. No genera una cuenta por pagar — el asiento contable reduce lo que se le debe al proveedor.\n\nPermiso requerido: `ERP_FACTURACION_RETENCION / crear`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetencionInput" } } } }, "responses": { "201": { "description": "Retención recién creada, en BORRADOR. importeTotal lleva el total retenido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComprobanteCreado" } } } }, "400": { "description": "El cuerpo no pasó la validación, o una regla de negocio lo rechazó.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No hay sesión activa.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "La sesión no tiene el permiso que exige el endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Alguna de las entidades referenciadas (cliente, proveedor, punto de emisión, comprobante) no existe en esta empresa.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado actual del documento.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Falta configuración de la empresa (certificado P12, establecimiento, punto de emisión).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Se superó el límite de peticiones.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/erp/facturacion/guia-remision": { "post": { "tags": [ "Facturación" ], "operationId": "crearGuiaRemision", "summary": "Crear una guía de remisión (comprobante 06)", "description": "Crea una guía de remisión: documento de transporte, sin precios ni impuestos. No mueve inventario ni genera cartera. Documenta transportista, placa, fechas de transporte y destinatarios con sus líneas de detalle.\n\nPermiso requerido: `ERP_FACTURACION_GUIA_REMISION / crear`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GuiaRemisionInput" } } } }, "responses": { "201": { "description": "Guía de remisión recién creada, en BORRADOR y sin firmar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GuiaRemisionCreada" } } } }, "400": { "description": "El cuerpo no pasó la validación, o una regla de negocio lo rechazó.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No hay sesión activa.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "La sesión no tiene el permiso que exige el endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Alguna de las entidades referenciadas (cliente, proveedor, punto de emisión, comprobante) no existe en esta empresa.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado actual del documento.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Falta configuración de la empresa (certificado P12, establecimiento, punto de emisión).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Se superó el límite de peticiones.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/erp/facturacion/liquidacion-compra": { "post": { "tags": [ "Facturación" ], "operationId": "crearLiquidacionCompra", "summary": "Crear una liquidación de compra (comprobante 03)", "description": "Crea una liquidación de compra: la emite el COMPRADOR a un proveedor que no puede emitir su propia factura. Al revés que la factura, genera una ENTRADA de inventario y una cuenta por pagar.\n\nPermiso requerido: `ERP_FACTURACION_LIQUIDACION / crear`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LiquidacionInput" } } } }, "responses": { "201": { "description": "Liquidación recién creada, en BORRADOR y sin firmar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComprobanteCreado" } } } }, "400": { "description": "El cuerpo no pasó la validación, o una regla de negocio lo rechazó.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No hay sesión activa.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "La sesión no tiene el permiso que exige el endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Alguna de las entidades referenciadas (cliente, proveedor, punto de emisión, comprobante) no existe en esta empresa.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado actual del documento.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Falta configuración de la empresa (certificado P12, establecimiento, punto de emisión).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Se superó el límite de peticiones.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/erp/sri/emitir": { "post": { "tags": [ "SRI" ], "operationId": "emitirComprobante", "summary": "Firmar, enviar y autorizar un comprobante ante el SRI", "description": "Encadena el ciclo completo BORRADOR → FIRMADO → ENVIADO → AUTORIZADO en una sola llamada: firma el XML con el certificado P12 de la empresa, lo transmite al SRI, consulta la autorización y envía el RIDE por correo al receptor. ES IRREVERSIBLE: una vez transmitido, el comprobante existe fiscalmente. La consulta de autorización hace polling y la llamada puede tardar hasta ~60 s. Responde 200 incluso cuando el SRI devuelve o no autoriza el documento: el veredicto está en `data.estado` y en `sriResponse`, no en el status HTTP.\n\nPermiso requerido: `ERP_FACTURACION_COMPROBANTES / editar`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmitirInput" } } } }, "responses": { "200": { "description": "Estado final del ciclo y lo que respondió el SRI en cada fase.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResultadoEmision" } } } }, "400": { "description": "El cuerpo no pasó la validación, o una regla de negocio lo rechazó.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No hay sesión activa.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "La sesión no tiene el permiso que exige el endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Alguna de las entidades referenciadas (cliente, proveedor, punto de emisión, comprobante) no existe en esta empresa.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado actual del documento.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Falta configuración de la empresa (certificado P12, establecimiento, punto de emisión).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Se superó el límite de peticiones.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "schemas": { "Error": { "description": "Cuerpo de error del ERP.", "type": "object", "properties": { "error": { "type": "string", "description": "Frase HTTP del error (Bad Request, Not Found, Conflict, ...). Apta para mostrar tal cual." }, "message": { "type": "string", "description": "Explicación en prosa, en español, con la acción correctiva." }, "details": { "description": "Errores por campo cuando falló la validación del cuerpo.", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "error", "message" ] }, "FacturaInput": { "description": "Cuerpo de creación de una factura.", "type": "object", "properties": { "puntoEmisionId": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "clienteId": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "fechaEmision": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "direccionReceptor": { "type": "string", "maxLength": 300 }, "detalles": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "productoId": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "codigoPrincipal": { "type": "string", "minLength": 1, "maxLength": 25 }, "codigoAuxiliar": { "type": "string", "maxLength": 25 }, "descripcion": { "type": "string", "minLength": 1, "maxLength": 300 }, "cantidad": { "type": "number", "exclusiveMinimum": 0 }, "precioUnitario": { "type": "number", "minimum": 0 }, "descuento": { "default": 0, "type": "number", "minimum": 0 }, "codigoImpuesto": { "default": "2", "type": "string" }, "codigoPorcentaje": { "default": "4", "type": "string" }, "tarifa": { "default": 15, "type": "number" }, "tipo": { "default": "PRODUCTO", "type": "string", "enum": [ "PRODUCTO", "SERVICIO" ] }, "bodegaId": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "codigoPrincipal", "descripcion", "cantidad", "precioUnitario" ] } }, "pagos": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "formaPago": { "type": "string", "minLength": 1, "maxLength": 2 }, "monto": { "type": "number", "exclusiveMinimum": 0 }, "plazo": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "unidadTiempo": { "type": "string", "maxLength": 20 } }, "required": [ "formaPago", "monto" ] } }, "infoAdicional": { "type": "array", "items": { "type": "object", "properties": { "nombre": { "type": "string", "minLength": 1, "maxLength": 300 }, "valor": { "type": "string", "minLength": 1 } }, "required": [ "nombre", "valor" ] } } }, "required": [ "puntoEmisionId", "clienteId", "fechaEmision", "detalles", "pagos" ] }, "ComprobanteCreado": { "description": "Comprobante recién creado, en BORRADOR y sin firmar.", "type": "object", "properties": { "id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Id interno del comprobante en el ERP." }, "claveAcceso": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Clave de acceso de 49 dígitos con la que el SRI identifica el documento." }, "establecimiento": { "type": "string", "description": "Código del establecimiento, 3 dígitos (ej. 001)." }, "puntoEmision": { "type": "string", "description": "Código del punto de emisión, 3 dígitos (ej. 001)." }, "secuencial": { "type": "string", "description": "Secuencial asignado, 9 dígitos (ej. 000000123)." }, "fechaEmision": { "type": "string", "description": "Fecha de emisión en formato YYYY-MM-DD." }, "estado": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Estado del documento recién creado. Siempre BORRADOR: todavía no se firmó ni se envió al SRI." }, "importeTotal": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Total del comprobante, como string con 2 decimales." }, "razonSocialReceptor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Razón social del receptor." }, "xmlOriginal": { "type": "string", "description": "XML del comprobante sin firmar." } }, "required": [ "id", "claveAcceso", "establecimiento", "puntoEmision", "secuencial", "fechaEmision", "estado", "importeTotal", "razonSocialReceptor", "xmlOriginal" ] }, "NotaCreditoInput": { "description": "Cuerpo de creación de una nota de crédito.", "type": "object", "properties": { "puntoEmisionId": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "clienteId": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "bodegaId": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "fechaEmision": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "docModificadoTipo": { "default": "01", "type": "string" }, "docModificadoNumero": { "type": "string", "minLength": 1, "maxLength": 17 }, "docModificadoFecha": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "motivo": { "type": "string", "minLength": 1, "maxLength": 300 }, "detalles": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "productoId": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "codigoPrincipal": { "type": "string", "minLength": 1, "maxLength": 25 }, "codigoAuxiliar": { "type": "string", "maxLength": 25 }, "descripcion": { "type": "string", "minLength": 1, "maxLength": 300 }, "cantidad": { "type": "number", "exclusiveMinimum": 0 }, "precioUnitario": { "type": "number", "minimum": 0 }, "descuento": { "default": 0, "type": "number", "minimum": 0 }, "codigoImpuesto": { "default": "2", "type": "string" }, "codigoPorcentaje": { "default": "4", "type": "string" }, "tarifa": { "default": 15, "type": "number" }, "tipo": { "default": "PRODUCTO", "type": "string", "enum": [ "PRODUCTO", "SERVICIO" ] } }, "required": [ "codigoPrincipal", "descripcion", "cantidad", "precioUnitario" ] } }, "infoAdicional": { "type": "array", "items": { "type": "object", "properties": { "nombre": { "type": "string", "minLength": 1, "maxLength": 300 }, "valor": { "type": "string", "minLength": 1 } }, "required": [ "nombre", "valor" ] } } }, "required": [ "puntoEmisionId", "clienteId", "fechaEmision", "docModificadoNumero", "docModificadoFecha", "motivo", "detalles" ] }, "NotaCreditoCreada": { "description": "Nota de crédito recién creada, en BORRADOR y sin firmar.", "type": "object", "properties": { "id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "claveAcceso": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "establecimiento": { "type": "string" }, "puntoEmision": { "type": "string" }, "secuencial": { "type": "string" }, "fechaEmision": { "type": "string" }, "estado": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "importeTotal": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "razonSocialReceptor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "docModificadoNumero": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Número completo de la factura que esta nota de crédito modifica (001-001-000000123)." }, "xmlOriginal": { "type": "string" } }, "required": [ "id", "claveAcceso", "establecimiento", "puntoEmision", "secuencial", "fechaEmision", "estado", "importeTotal", "razonSocialReceptor", "docModificadoNumero", "xmlOriginal" ] }, "NotaDebitoInput": { "description": "Cuerpo de creación de una nota de débito.", "type": "object", "properties": { "puntoEmisionId": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "clienteId": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "bodegaId": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "fechaEmision": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "docModificadoTipo": { "default": "01", "type": "string" }, "docModificadoNumero": { "type": "string", "minLength": 1, "maxLength": 17 }, "docModificadoFecha": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "motivos": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "razon": { "type": "string", "minLength": 1, "maxLength": 300 }, "valor": { "type": "number", "exclusiveMinimum": 0 }, "tipo": { "default": "SERVICIO", "type": "string", "enum": [ "PRODUCTO", "SERVICIO" ] }, "productoId": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "cantidad": { "type": "number", "exclusiveMinimum": 0 } }, "required": [ "razon", "valor" ] } }, "codigoImpuesto": { "default": "2", "type": "string" }, "codigoPorcentaje": { "default": "4", "type": "string" }, "tarifa": { "default": 15, "type": "number" }, "pagos": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "formaPago": { "type": "string", "minLength": 1, "maxLength": 2 }, "monto": { "type": "number", "exclusiveMinimum": 0 }, "plazo": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "unidadTiempo": { "type": "string", "maxLength": 20 } }, "required": [ "formaPago", "monto" ] } }, "infoAdicional": { "type": "array", "items": { "type": "object", "properties": { "nombre": { "type": "string", "minLength": 1, "maxLength": 300 }, "valor": { "type": "string", "minLength": 1 } }, "required": [ "nombre", "valor" ] } } }, "required": [ "puntoEmisionId", "clienteId", "fechaEmision", "docModificadoNumero", "docModificadoFecha", "motivos", "pagos" ] }, "RetencionInput": { "description": "Cuerpo de creación de un comprobante de retención.", "type": "object", "properties": { "puntoEmisionId": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "proveedorId": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "fechaEmision": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "periodoFiscal": { "type": "string", "pattern": "^\\d{2}\\/\\d{4}$" }, "retenciones": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "codSustento": { "default": "01", "type": "string" }, "codDocSustento": { "default": "01", "type": "string" }, "numDocSustento": { "type": "string", "minLength": 1, "maxLength": 17 }, "fechaEmisionDocSustento": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "pagoLocExt": { "default": "01", "type": "string" }, "codigoImpuesto": { "type": "string" }, "codigoRetencion": { "type": "string" }, "baseImponible": { "type": "number", "exclusiveMinimum": 0 }, "porcentajeRetener": { "type": "number", "minimum": 0 }, "valorRetenido": { "type": "number", "minimum": 0 } }, "required": [ "numDocSustento", "fechaEmisionDocSustento", "codigoImpuesto", "codigoRetencion", "baseImponible", "porcentajeRetener", "valorRetenido" ] } }, "infoAdicional": { "type": "array", "items": { "type": "object", "properties": { "nombre": { "type": "string", "minLength": 1, "maxLength": 300 }, "valor": { "type": "string", "minLength": 1 } }, "required": [ "nombre", "valor" ] } } }, "required": [ "puntoEmisionId", "proveedorId", "fechaEmision", "periodoFiscal", "retenciones" ] }, "GuiaRemisionInput": { "description": "Cuerpo de creación de una guía de remisión.", "type": "object", "properties": { "puntoEmisionId": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "fechaEmision": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "dirPartida": { "type": "string", "minLength": 1, "maxLength": 300 }, "razonSocialTransportista": { "type": "string", "minLength": 1, "maxLength": 300 }, "tipoIdentificacionTransportista": { "type": "string", "minLength": 1, "maxLength": 2 }, "rucTransportista": { "type": "string", "minLength": 1, "maxLength": 20 }, "placa": { "type": "string", "minLength": 1, "maxLength": 20 }, "fechaIniTransporte": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "fechaFinTransporte": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "email": { "type": "string", "maxLength": 300, "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "destinatarios": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "identificacionDestinatario": { "type": "string", "pattern": "^(\\d{10}|\\d{13})$" }, "razonSocialDestinatario": { "type": "string", "minLength": 1, "maxLength": 300 }, "dirDestinatario": { "type": "string", "minLength": 1, "maxLength": 300 }, "motivoTraslado": { "type": "string", "minLength": 1, "maxLength": 300 }, "docAduaneroUnico": { "type": "string", "maxLength": 20 }, "codEstabDestino": { "type": "string", "maxLength": 3 }, "ruta": { "type": "string", "maxLength": 300 }, "codDocSustento": { "type": "string", "maxLength": 2 }, "numDocSustento": { "type": "string", "maxLength": 17 }, "numAutDocSustento": { "type": "string", "maxLength": 49 }, "fechaEmisionDocSustento": { "type": "string" }, "detalles": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "codigoInterno": { "type": "string", "minLength": 1, "maxLength": 25 }, "codigoAdicional": { "type": "string", "maxLength": 25 }, "descripcion": { "type": "string", "minLength": 1, "maxLength": 300 }, "cantidad": { "type": "number", "exclusiveMinimum": 0 } }, "required": [ "codigoInterno", "descripcion", "cantidad" ] } } }, "required": [ "identificacionDestinatario", "razonSocialDestinatario", "dirDestinatario", "motivoTraslado", "detalles" ] } }, "infoAdicional": { "type": "array", "items": { "type": "object", "properties": { "nombre": { "type": "string", "minLength": 1, "maxLength": 300 }, "valor": { "type": "string", "minLength": 1 } }, "required": [ "nombre", "valor" ] } } }, "required": [ "puntoEmisionId", "fechaEmision", "dirPartida", "razonSocialTransportista", "tipoIdentificacionTransportista", "rucTransportista", "placa", "fechaIniTransporte", "fechaFinTransporte", "email", "destinatarios" ] }, "GuiaRemisionCreada": { "description": "Guía de remisión recién creada, en BORRADOR y sin firmar.", "type": "object", "properties": { "id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "numero": { "type": "string", "description": "Número completo del documento, ya compuesto: 001-001-000000123." }, "claveAcceso": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "fechaEmision": { "type": "string" }, "estado": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "numero", "claveAcceso", "fechaEmision", "estado" ] }, "LiquidacionInput": { "description": "Cuerpo de creación de una liquidación de compra.", "type": "object", "properties": { "puntoEmisionId": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "proveedorId": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "fechaEmision": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "detalles": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "productoId": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "codigoPrincipal": { "type": "string", "minLength": 1, "maxLength": 25 }, "codigoAuxiliar": { "type": "string", "maxLength": 25 }, "descripcion": { "type": "string", "minLength": 1, "maxLength": 300 }, "cantidad": { "type": "number", "exclusiveMinimum": 0 }, "precioUnitario": { "type": "number", "minimum": 0 }, "descuento": { "default": 0, "type": "number", "minimum": 0 }, "codigoImpuesto": { "default": "2", "type": "string" }, "codigoPorcentaje": { "default": "4", "type": "string" }, "tarifa": { "default": 15, "type": "number" }, "tipo": { "default": "PRODUCTO", "type": "string", "enum": [ "PRODUCTO", "SERVICIO" ] }, "bodegaId": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "codigoPrincipal", "descripcion", "cantidad", "precioUnitario" ] } }, "pagos": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "formaPago": { "type": "string", "minLength": 1, "maxLength": 2 }, "monto": { "type": "number", "exclusiveMinimum": 0 }, "plazo": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "unidadTiempo": { "type": "string", "maxLength": 20 } }, "required": [ "formaPago", "monto" ] } }, "infoAdicional": { "type": "array", "items": { "type": "object", "properties": { "nombre": { "type": "string", "minLength": 1, "maxLength": 300 }, "valor": { "type": "string", "minLength": 1 } }, "required": [ "nombre", "valor" ] } } }, "required": [ "puntoEmisionId", "proveedorId", "fechaEmision", "detalles", "pagos" ] }, "EmitirInput": { "description": "Id del comprobante en BORRADOR que se quiere emitir.", "type": "object", "properties": { "comprobanteId": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "Id del comprobante en estado BORRADOR que se quiere emitir." } }, "required": [ "comprobanteId" ] }, "ResultadoEmision": { "description": "Estado final del ciclo y lo que respondió el SRI en cada fase.", "type": "object", "properties": { "message": { "type": "string", "description": "Resumen legible de cómo terminó el ciclo." }, "data": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {}, "description": "Fila del comprobante ya actualizada con el estado final." }, "lifecycle": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {}, "description": "Qué fases del ciclo se completaron (firma, envío, autorización)." }, "sriResponse": { "description": "Lo que devolvió el SRI en cada fase que llegó a ejecutarse.", "type": "object", "properties": { "recepcion": { "description": "Respuesta del SRI a la recepción del XML.", "type": "object", "properties": { "estado": { "type": "string" }, "mensajes": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } } }, "required": [ "estado", "mensajes" ] }, "autorizacion": { "description": "Respuesta del SRI a la consulta de autorización.", "type": "object", "properties": { "estado": { "type": "string" }, "numeroAutorizacion": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "fechaAutorizacion": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "mensajes": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } } }, "required": [ "estado", "numeroAutorizacion", "fechaAutorizacion", "mensajes" ] } } }, "emailAuto": { "description": "Detalle del envío automático del RIDE al receptor, si aplicó.", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "error": { "description": "Motivo del rechazo del SRI, cuando el estado final no es AUTORIZADO.", "type": "string" } }, "required": [ "message", "data", "lifecycle" ] } }, "securitySchemes": { "sesionWeb": { "type": "apiKey", "in": "cookie", "name": "__Secure-better-auth.session_token", "description": "Cookie de sesión de Better Auth. Se obtiene iniciando sesión en la aplicación web. En producción (https) se llama `__Secure-better-auth.session_token`; en desarrollo sobre http, `better-auth.session_token`." } } }, "externalDocs": { "description": "Documentación de conexión por MCP", "url": "https://app.sipagentai.com/docs/mcp" } }