{ "openapi": "3.1.0", "info": { "title": "AZUR · API v2", "version": "2.1.0", "description": "API para **registrar comprobantes en AZUR**, igual que si se hicieran desde el portal.\n\n## Qué hace y qué no\n\nEsta parte de la API **guarda**. Un documento se crea como borrador, se puede consultar y\neditar, y cuando está listo se marca para enviar: a partir de ahí AZUR se encarga de generar\nel XML, firmarlo y mandarlo al SRI, exactamente igual que cuando alguien pulsa el botón en la\npantalla.\n\nSi lo que quiere es **emitir de una sola vez**, sin borrador, use los endpoints\n`/{tipo}/emision`, que llevan años funcionando y no cambian.\n\n## Lo que hay que saber antes de empezar\n\n- **El ambiente lo fija la credencial**, no la llamada. Una credencial `azur_live_` emite en\n producción y una `azur_test_` en pruebas. No hay forma de equivocarse desde el código.\n- **Los totales los calcula el servidor.** Si usted los envía, se comparan con los calculados\n y se le avisa de la diferencia, pero se usan siempre los del servidor.\n- **Mande `Idempotency-Key` en todo lo que escriba.** Si se corta la conexión y reintenta, la\n misma clave devuelve el resultado original en vez de crear un segundo documento.\n- **Cuando una búsqueda es ambigua se devuelven todos los candidatos**, nunca el que mejor\n casa. Mire el campo `unico`: si es `false`, hay que elegir.\n\n## Errores\n\nCada error trae un `codigo` estable —`cupo_agotado`, `secuencial_ocupado`,\n`documento_no_editable`…— y un `reintentable` que dice si tiene sentido volver a intentarlo.\nEl `mensaje` es para enseñárselo a una persona; el `codigo` es para el programa." }, "servers": [ { "url": "https://azur.com.ec/plataforma/api/v2" } ], "security": [ { "credencial": [] } ], "tags": [ { "name": "Emisión directa (api_key)", "description": "La API de siempre para **emitir un comprobante en una sola llamada**: se manda el JSON completo y AZUR genera el XML, lo firma, lo envía al SRI y responde con la clave de acceso. Es la que usan la mayoría de integraciones, plugins y sistemas propios.\n\n**Autenticación:** el `api_key` de su **punto de emisión** (empieza con `API_`), en el campo `api_key` del cuerpo **o** en la cabecera `X-Api-Key` (también `Authorization: Bearer`). Si viene en los dos, vale el del cuerpo. No es la credencial `azur_live_` / `azur_test_`.\n\n**Ambiente:** lo define el punto de emisión (Pruebas o Producción, en Configuración → Puntos de emisión), no la llamada.\n\n**Secuencial:** envíe `\"manejo_interno_secuencia\": \"SI\"` en `emisor` y AZUR asigna el siguiente, sin duplicados. Si usted manda su propio `secuencial`, el mismo comprobante (misma fecha y secuencial) admite **5 intentos por minuto** (luego responde 429 con `Retry-After`).\n\n**Después de emitir:** consulte el estado y los enlaces del PDF/XML con `POST /consulta/comprobante` (abajo), o reciba el aviso por webhook.\n\n**Fechas:** `emisor.fecha_emision` en formato `AAAA/MM/DD`.\n\n### Tipo de identificación (`tipo_identificacion`)\n\n| Código | Identificación |\n|---|---|\n| `04` | RUC (13 dígitos) |\n| `05` | Cédula (10 dígitos) |\n| `06` | Pasaporte |\n| `07` | Consumidor final |\n| `08` | Identificación del exterior |\n| `09` | Placa |\n\n### Tarifa de IVA (`tipo_iva`)\n\n| Código | Tarifa |\n|---|---|\n| `0` | 0% |\n| `4` | 15% |\n| `3` | 14% |\n| `5` | 5% |\n| `8` | 8% (turístico) |\n| `10` | 13% |\n| `6` | No objeto de IVA |\n| `7` | Exento de IVA |\n\n### Formas de pago (`pagos[].tipo`)\n\n| Código | Forma de pago |\n|---|---|\n| `01` | Efectivo / sin sistema financiero |\n| `16` | Tarjeta de débito |\n| `17` | Dinero electrónico |\n| `18` | Tarjeta prepago |\n| `19` | Tarjeta de crédito |\n| `20` | Otros con sistema financiero |\n| `21` | Endoso de títulos |\n" }, { "name": "Comprobantes", "description": "Guardar, consultar y enviar los nueve tipos de documento." }, { "name": "Búsqueda", "description": "Encontrar clientes, proveedores y productos por texto." }, { "name": "Cuenta", "description": "Contexto de trabajo, plan contratado y resumen de ventas." }, { "name": "Catálogos", "description": "Alta, cambio y baja de clientes, proveedores, transportistas y productos." }, { "name": "Inventario", "description": "Existencias, kardex y movimientos de bodega." }, { "name": "Contabilidad", "description": "Plan de cuentas, centros de costo y asientos manuales." }, { "name": "Reportes", "description": "El ATS mensual del SRI y las ventas y compras agrupadas." }, { "name": "Cartera", "description": "Cuentas por cobrar y por pagar: quién debe, estado de cuenta y registro de cobros." }, { "name": "Recibidos", "description": "Los comprobantes que le emiten a usted: importarlos del SRI, verlos y pasarlos a compra." }, { "name": "Webhooks", "description": "Avisos automáticos cuando un comprobante cambia de estado." }, { "name": "Sesión", "description": "Acceso de personas desde la app móvil y cambio de contexto." } ], "paths": { "/factura/emision": { "post": { "tags": [ "Emisión directa (api_key)" ], "operationId": "emision_directa_factura", "x-azur-visibilidad": "publico", "summary": "Emitir factura (codDoc 01)", "description": "Emite el comprobante en una sola llamada: valida, genera el XML, firma y envía al SRI. Responde con la clave de acceso; el estado final (autorizado o no) se consulta con `POST /consulta/comprobante` o llega por webhook. El ejemplo muestra todos los bloques; los códigos de cada campo están en la descripción del grupo.", "deprecated": false, "security": [ { "api_key_emision": [] }, [] ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "codigoDoc", "emisor" ], "additionalProperties": true, "properties": { "api_key": { "type": "string", "description": "api_key del punto de emisión (o en la cabecera X-Api-Key)." }, "codigoDoc": { "type": "string", "enum": [ "01" ] }, "emisor": { "type": "object", "description": "fecha_emision (AAAA/MM/DD), secuencial o manejo_interno_secuencia = \"SI\"." } } }, "example": { "api_key": "TU_API_KEY", "codigoDoc": "01", "emisor": { "fecha_emision": "2026/07/13", "secuencial": "000000123", "manejo_interno_secuencia": "SI" }, "comprador": { "tipo_identificacion": "05", "identificacion": "1712345678", "razon_social": "JUAN PEREZ LOPEZ", "direccion": "Av. Amazonas N34-56, Quito", "telefono": "022345678", "celular": "0991234567", "correo": "juan.perez@ejemplo.com" }, "items": [ { "codigo_principal": "PROD-001", "codigo_auxiliar": "AUX-001", "descripcion": "Laptop HP 15 Core i5", "cantidad": 2, "precio_unitario": 850, "descuento": 50, "tipoproducto": 1, "tipo_iva": 4, "unidad_medida": 1, "detalles_adicionales": [ { "nombre": "Marca", "detalle": "HP" }, { "nombre": "Garantia", "detalle": "12 meses" } ] }, { "codigo_principal": "SERV-010", "descripcion": "Servicio de instalacion", "cantidad": 1, "precio_unitario": 30, "tipoproducto": 2, "tipo_iva": 4 } ], "pagos": [ { "tipo": "20", "total": 1918, "tiempo": "dias", "plazo": 30 } ], "informacion_adicional": [ { "nombre": "Vendedor", "detalle": "Maria Gomez" } ] } } } }, "responses": { "200": { "description": "Comprobante recibido y enviado al SRI", "content": { "application/json": { "examples": { "correcto": { "summary": "Correcto", "value": { "creado": true, "claveacceso": "0110202601179999999900110010010000001231234567817" } }, "error": { "summary": "Error de validación o de negocio (también responde 200)", "value": { "creado": false, "claveacceso": "", "errors": { "error": "La fecha no debe estar vacia" } } }, "clave_invalida": { "summary": "api_key inexistente (también responde 200, no 401)", "value": { "creado": false, "claveacceso": "", "errors": { "error": "Api_key No existe" } } } } } } }, "429": { "description": "Demasiados intentos del mismo comprobante (5 por minuto). Respete la cabecera Retry-After." } } } }, "/credito/emision": { "post": { "tags": [ "Emisión directa (api_key)" ], "operationId": "emision_directa_credito", "x-azur-visibilidad": "publico", "summary": "Emitir nota de crédito (codDoc 04)", "description": "Emite el comprobante en una sola llamada: valida, genera el XML, firma y envía al SRI. Responde con la clave de acceso; el estado final (autorizado o no) se consulta con `POST /consulta/comprobante` o llega por webhook. El ejemplo muestra todos los bloques; los códigos de cada campo están en la descripción del grupo.", "deprecated": false, "security": [ { "api_key_emision": [] }, [] ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "codigoDoc", "emisor" ], "additionalProperties": true, "properties": { "api_key": { "type": "string", "description": "api_key del punto de emisión (o en la cabecera X-Api-Key)." }, "codigoDoc": { "type": "string", "enum": [ "04" ] }, "emisor": { "type": "object", "description": "fecha_emision (AAAA/MM/DD), secuencial o manejo_interno_secuencia = \"SI\"." } } }, "example": { "api_key": "TU_API_KEY", "codigoDoc": "04", "emisor": { "fecha_emision": "2026/07/13", "manejo_interno_secuencia": "SI" }, "documento_modificado": { "codigo_documento_sustento": 1, "numero_documento_sustento": 122, "fecha_documento_sustento": "2026/07/01", "motivo": "Devolucion de producto defectuoso", "anula_comprobante": "NO" }, "comprador": { "tipo_identificacion": "05", "identificacion": "1712345678", "razon_social": "JUAN PEREZ LOPEZ", "direccion": "Av. Amazonas N34-56, Quito", "correo": "juan.perez@ejemplo.com" }, "items": [ { "codigo_principal": "PROD-001", "descripcion": "Laptop HP 15 Core i5", "cantidad": 1, "precio_unitario": 850, "tipoproducto": 1, "tipo_iva": 4 } ], "informacion_adicional": [ { "nombre": "Motivo", "detalle": "Producto defectuoso" } ] } } } }, "responses": { "200": { "description": "Comprobante recibido y enviado al SRI", "content": { "application/json": { "examples": { "correcto": { "summary": "Correcto", "value": { "creado": true, "claveacceso": "0110202601179999999900110010010000001231234567817" } }, "error": { "summary": "Error de validación o de negocio (también responde 200)", "value": { "creado": false, "claveacceso": "", "errors": { "error": "La fecha no debe estar vacia" } } }, "clave_invalida": { "summary": "api_key inexistente (también responde 200, no 401)", "value": { "creado": false, "claveacceso": "", "errors": { "error": "Api_key No existe" } } } } } } }, "429": { "description": "Demasiados intentos del mismo comprobante (5 por minuto). Respete la cabecera Retry-After." } } } }, "/debito/emision": { "post": { "tags": [ "Emisión directa (api_key)" ], "operationId": "emision_directa_debito", "x-azur-visibilidad": "publico", "summary": "Emitir nota de débito (codDoc 05)", "description": "Emite el comprobante en una sola llamada: valida, genera el XML, firma y envía al SRI. Responde con la clave de acceso; el estado final (autorizado o no) se consulta con `POST /consulta/comprobante` o llega por webhook. El ejemplo muestra todos los bloques; los códigos de cada campo están en la descripción del grupo.", "deprecated": false, "security": [ { "api_key_emision": [] }, [] ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "codigoDoc", "emisor" ], "additionalProperties": true, "properties": { "api_key": { "type": "string", "description": "api_key del punto de emisión (o en la cabecera X-Api-Key)." }, "codigoDoc": { "type": "string", "enum": [ "05" ] }, "emisor": { "type": "object", "description": "fecha_emision (AAAA/MM/DD), secuencial o manejo_interno_secuencia = \"SI\"." } } }, "example": { "api_key": "TU_API_KEY", "codigoDoc": "05", "emisor": { "fecha_emision": "2026/07/13", "manejo_interno_secuencia": "SI" }, "documento_modificado": { "codigo_documento_sustento": 1, "numero_documento_sustento": 118, "fecha_documento_sustento": "2026/06/20" }, "comprador": { "tipo_identificacion": "04", "identificacion": "1790012345001", "razon_social": "COMERCIAL XYZ CIA LTDA", "direccion": "Av. 6 de Diciembre y Colon, Quito", "correo": "pagos@xyz.com" }, "modificaciones": [ { "razon_modificacion": "Interes por mora", "valor_modificacion": 25, "tipo_modificacion": 4 } ], "pagos": [ { "tipo": "20", "total": 28.75, "tiempo": "dias", "plazo": 15 } ] } } } }, "responses": { "200": { "description": "Comprobante recibido y enviado al SRI", "content": { "application/json": { "examples": { "correcto": { "summary": "Correcto", "value": { "creado": true, "claveacceso": "0110202601179999999900110010010000001231234567817" } }, "error": { "summary": "Error de validación o de negocio (también responde 200)", "value": { "creado": false, "claveacceso": "", "errors": { "error": "La fecha no debe estar vacia" } } }, "clave_invalida": { "summary": "api_key inexistente (también responde 200, no 401)", "value": { "creado": false, "claveacceso": "", "errors": { "error": "Api_key No existe" } } } } } } }, "429": { "description": "Demasiados intentos del mismo comprobante (5 por minuto). Respete la cabecera Retry-After." } } } }, "/retencionats/emision": { "post": { "tags": [ "Emisión directa (api_key)" ], "operationId": "emision_directa_retencionats", "x-azur-visibilidad": "publico", "summary": "Emitir comprobante de retención 2.0 (ATS) (codDoc 07)", "description": "**Recomendada.** Retención con el esquema 2.0.0 del SRI, el que pide el ATS: además de las retenciones lleva el **documento sustento** (la factura del proveedor) con sus bases por tarifa de IVA y la forma de pago. AZUR registra la compra por dentro y la deja vinculada a la retención y a su cuenta por pagar.\n\n**`sustento`** (obligatorio): `codigo_sustento_tributario` (tabla 5 del SRI, p. ej. 01 crédito tributario de IVA), `codigo_documento_sustento` (01 factura, 03 liquidación, 19 dividendos…), `numero_documento_sustento` (15 dígitos, sin guiones), `numero_autorizacion` de ese documento, `fecha_documento_sustento` y `fecha_registro_contable` (AAAA/MM/DD), y **`items`** (como en la factura: código, descripción, `tipo_iva`, cantidad, precio) **o** `gastos` (`descripcion`, `tipo_iva`, `subtotal_iva`, `subtotal_siniva`, `subtotal_ivacero`). Con `codigo_documento_sustento` = 19 se exige además `dividendos` (`impuestorenta`, `periodo`, `descripcion`, `fechapago`).\n\n**`retenciones`**: `codigoimpuesto` (1 renta · 2 IVA · 6 ISD), `codigo_retencion`, `base_imponible`, `porcentaje_retencion` y `valor_retenido`. Aquí NO se repite el documento sustento en cada línea: sale de `sustento`. Si no se manda forma de pago, se usa 20 (otros con utilización del sistema financiero).\n\nEmite el comprobante en una sola llamada: valida, genera el XML, firma y envía al SRI. Responde con la clave de acceso; el estado final (autorizado o no) se consulta con `POST /consulta/comprobante` o llega por webhook. El ejemplo muestra todos los bloques; los códigos de cada campo están en la descripción del grupo.", "deprecated": false, "security": [ { "api_key_emision": [] }, [] ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "codigoDoc", "emisor" ], "additionalProperties": true, "properties": { "api_key": { "type": "string", "description": "api_key del punto de emisión (o en la cabecera X-Api-Key)." }, "codigoDoc": { "type": "string", "enum": [ "07" ] }, "emisor": { "type": "object", "description": "fecha_emision (AAAA/MM/DD), secuencial o manejo_interno_secuencia = \"SI\"." } } }, "example": { "api_key": "TU_API_KEY", "codigoDoc": "07", "emisor": { "fecha_emision": "2026/07/13", "manejo_interno_secuencia": "SI" }, "proveedor": { "tipo_identificacion": "04", "identificacion": "1790012345001", "razon_social": "PROVEEDORA NACIONAL S.A.", "direccion": "Av. Eloy Alfaro N45-12, Quito", "correo": "facturacion@proveedora.com" }, "sustento": { "codigo_sustento_tributario": "01", "codigo_documento_sustento": "01", "numero_documento_sustento": "001001000000123", "numero_autorizacion": "1007202601179001234500110010010000001231234567812", "fecha_documento_sustento": "2026/07/10", "fecha_registro_contable": "2026/07/13", "items": [ { "codigo_principal": "SERV-001", "descripcion": "Mantenimiento de equipos", "tipoproducto": 2, "tipo_iva": 4, "cantidad": 1, "precio_unitario": 1000, "descuento": 0 } ] }, "retenciones": [ { "codigoimpuesto": 1, "codigo_retencion": "3440", "base_imponible": 1000, "porcentaje_retencion": 2.75, "valor_retenido": 27.5 }, { "codigoimpuesto": 2, "codigo_retencion": "10", "base_imponible": 150, "porcentaje_retencion": 20, "valor_retenido": 30 } ], "informacion_adicional": [ { "nombre": "Correo", "detalle": "facturacion@proveedora.com" } ] } } } }, "responses": { "200": { "description": "Comprobante recibido y enviado al SRI", "content": { "application/json": { "examples": { "correcto": { "summary": "Correcto", "value": { "creado": true, "claveacceso": "0110202601179999999900110010010000001231234567817" } }, "error": { "summary": "Error de validación o de negocio (también responde 200)", "value": { "creado": false, "claveacceso": "", "errors": { "error": "La fecha no debe estar vacia" } } }, "clave_invalida": { "summary": "api_key inexistente (también responde 200, no 401)", "value": { "creado": false, "claveacceso": "", "errors": { "error": "Api_key No existe" } } } } } } }, "429": { "description": "Demasiados intentos del mismo comprobante (5 por minuto). Respete la cabecera Retry-After." } } } }, "/retencion/emision": { "post": { "tags": [ "Emisión directa (api_key)" ], "operationId": "emision_directa_retencion", "x-azur-visibilidad": "publico", "summary": "Emitir comprobante de retención 1.0 (obsoleta) (codDoc 07)", "description": "**Obsoleta: use `POST /retencionats/emision` (retención 2.0).** Esta versión sigue funcionando igual para las integraciones que ya la usan, pero emite con el esquema 1.0 del SRI, sin el documento sustento completo que pide el ATS.\n\nEmite el comprobante en una sola llamada: valida, genera el XML, firma y envía al SRI. Responde con la clave de acceso; el estado final (autorizado o no) se consulta con `POST /consulta/comprobante` o llega por webhook. El ejemplo muestra todos los bloques; los códigos de cada campo están en la descripción del grupo.", "deprecated": true, "security": [ { "api_key_emision": [] }, [] ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "codigoDoc", "emisor" ], "additionalProperties": true, "properties": { "api_key": { "type": "string", "description": "api_key del punto de emisión (o en la cabecera X-Api-Key)." }, "codigoDoc": { "type": "string", "enum": [ "07" ] }, "emisor": { "type": "object", "description": "fecha_emision (AAAA/MM/DD), secuencial o manejo_interno_secuencia = \"SI\"." } } }, "example": { "api_key": "TU_API_KEY", "codigoDoc": "07", "emisor": { "fecha_emision": "2026/07/13", "manejo_interno_secuencia": "SI" }, "proveedor": { "tipo_identificacion": "04", "identificacion": "1790012345001", "razon_social": "PROVEEDORA NACIONAL S.A.", "direccion": "Av. Eloy Alfaro N45-12, Quito", "correo": "facturacion@proveedora.com" }, "retenciones": [ { "base_imponible": 1000, "codigoimpuesto": 1, "codigo_retencion": "312", "porcentaje_retencion": 1.75, "valor_retenido": 17.5, "codigo_documento_sustento": "01", "numero_documento_sustento": "001001000000123", "fecha_documento_sustento": "2026/07/10" }, { "base_imponible": 150, "codigoimpuesto": 2, "codigo_retencion": "1", "porcentaje_retencion": 30, "valor_retenido": 45, "codigo_documento_sustento": "01", "numero_documento_sustento": "001001000000123", "fecha_documento_sustento": "2026/07/10" } ] } } } }, "responses": { "200": { "description": "Comprobante recibido y enviado al SRI", "content": { "application/json": { "examples": { "correcto": { "summary": "Correcto", "value": { "creado": true, "claveacceso": "0110202601179999999900110010010000001231234567817" } }, "error": { "summary": "Error de validación o de negocio (también responde 200)", "value": { "creado": false, "claveacceso": "", "errors": { "error": "La fecha no debe estar vacia" } } }, "clave_invalida": { "summary": "api_key inexistente (también responde 200, no 401)", "value": { "creado": false, "claveacceso": "", "errors": { "error": "Api_key No existe" } } } } } } }, "429": { "description": "Demasiados intentos del mismo comprobante (5 por minuto). Respete la cabecera Retry-After." } } } }, "/liquidacion/emision": { "post": { "tags": [ "Emisión directa (api_key)" ], "operationId": "emision_directa_liquidacion", "x-azur-visibilidad": "publico", "summary": "Emitir liquidación de compra (codDoc 03)", "description": "Emite el comprobante en una sola llamada: valida, genera el XML, firma y envía al SRI. Responde con la clave de acceso; el estado final (autorizado o no) se consulta con `POST /consulta/comprobante` o llega por webhook. El ejemplo muestra todos los bloques; los códigos de cada campo están en la descripción del grupo.", "deprecated": false, "security": [ { "api_key_emision": [] }, [] ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "codigoDoc", "emisor" ], "additionalProperties": true, "properties": { "api_key": { "type": "string", "description": "api_key del punto de emisión (o en la cabecera X-Api-Key)." }, "codigoDoc": { "type": "string", "enum": [ "03" ] }, "emisor": { "type": "object", "description": "fecha_emision (AAAA/MM/DD), secuencial o manejo_interno_secuencia = \"SI\"." } } }, "example": { "api_key": "TU_API_KEY", "codigoDoc": "03", "emisor": { "fecha_emision": "2026/07/13", "manejo_interno_secuencia": "SI" }, "proveedor": { "tipo_identificacion": "05", "identificacion": "1712345678", "razon_social": "AGRICULTOR SIN RUC", "direccion": "Comunidad El Rosario, Cotopaxi", "correo": "agricultor@ejemplo.com" }, "items": [ { "codigo_principal": "PAPA-01", "descripcion": "Quintal de papa chola", "cantidad": 20, "precio_unitario": 15, "tipoproducto": 1, "tipo_iva": 0 } ], "pagos": [ { "tipo": "01", "total": 300, "tiempo": "dias", "plazo": 0 } ] } } } }, "responses": { "200": { "description": "Comprobante recibido y enviado al SRI", "content": { "application/json": { "examples": { "correcto": { "summary": "Correcto", "value": { "creado": true, "claveacceso": "0110202601179999999900110010010000001231234567817" } }, "error": { "summary": "Error de validación o de negocio (también responde 200)", "value": { "creado": false, "claveacceso": "", "errors": { "error": "La fecha no debe estar vacia" } } }, "clave_invalida": { "summary": "api_key inexistente (también responde 200, no 401)", "value": { "creado": false, "claveacceso": "", "errors": { "error": "Api_key No existe" } } } } } } }, "429": { "description": "Demasiados intentos del mismo comprobante (5 por minuto). Respete la cabecera Retry-After." } } } }, "/guia/emision": { "post": { "tags": [ "Emisión directa (api_key)" ], "operationId": "emision_directa_guia", "x-azur-visibilidad": "publico", "summary": "Emitir guía de remisión (codDoc 06)", "description": "Emite el comprobante en una sola llamada: valida, genera el XML, firma y envía al SRI. Responde con la clave de acceso; el estado final (autorizado o no) se consulta con `POST /consulta/comprobante` o llega por webhook. El ejemplo muestra todos los bloques; los códigos de cada campo están en la descripción del grupo.", "deprecated": false, "security": [ { "api_key_emision": [] }, [] ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "codigoDoc", "emisor" ], "additionalProperties": true, "properties": { "api_key": { "type": "string", "description": "api_key del punto de emisión (o en la cabecera X-Api-Key)." }, "codigoDoc": { "type": "string", "enum": [ "06" ] }, "emisor": { "type": "object", "description": "fecha_emision (AAAA/MM/DD), secuencial o manejo_interno_secuencia = \"SI\"." } } }, "example": { "api_key": "TU_API_KEY", "codigoDoc": "06", "emisor": { "fecha_emision": "2026/07/13", "manejo_interno_secuencia": "SI" }, "transportista": { "tipo_identificacion": "04", "identificacion": "1790055566001", "razon_social": "TRANSPORTES RAPIDOS CIA LTDA", "direccion": "Panamericana Norte Km 5, Quito" }, "destinatario": { "tipo_identificacion": "04", "identificacion": "0990012345001", "razon_social": "DISTRIBUIDORA GUAYAS S.A.", "direccion": "Av. Las Americas, Guayaquil" }, "traslado": { "fecha_inicio_transporte": "2026/07/13", "fecha_fin_transporte": "2026/07/14", "direccion_destino": "Av. Las Americas, Guayaquil", "ruta": "Quito - Guayaquil via E25", "motivo_traslado": "Venta" }, "items": [ { "cantidad": 50, "codigo_principal": "PROD-001", "descripcion": "Laptop HP 15 Core i5", "unidad_medida": 1 } ] } } } }, "responses": { "200": { "description": "Comprobante recibido y enviado al SRI", "content": { "application/json": { "examples": { "correcto": { "summary": "Correcto", "value": { "creado": true, "claveacceso": "0110202601179999999900110010010000001231234567817" } }, "error": { "summary": "Error de validación o de negocio (también responde 200)", "value": { "creado": false, "claveacceso": "", "errors": { "error": "La fecha no debe estar vacia" } } }, "clave_invalida": { "summary": "api_key inexistente (también responde 200, no 401)", "value": { "creado": false, "claveacceso": "", "errors": { "error": "Api_key No existe" } } } } } } }, "429": { "description": "Demasiados intentos del mismo comprobante (5 por minuto). Respete la cabecera Retry-After." } } } }, "/clientes/nuevo": { "post": { "tags": [ "Emisión directa (api_key)" ], "operationId": "clasica_clientes_nuevo", "x-azur-visibilidad": "publico", "summary": "Crear o actualizar un cliente", "description": "Crea el cliente o actualiza sus datos si ya existe (por identificación); también su sucursal.", "security": [ { "api_key_emision": [] }, [] ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "api_key": "API_…", "comprador": { "tipo_identificacion": "04", "identificacion": "1790012345001", "razon_social": "EMPRESA EJEMPLO S.A.", "direccion": "Av. Amazonas y Colón, Quito", "telefono": "022345678", "correo": "facturas@ejemplo.com", "codigo_sucursal": "MATRIZ", "nombre_sucursal": "Matriz" } } } } }, "responses": { "200": { "description": "Correcto. Los rechazos (api_key inexistente, validación) también llegan con HTTP 200 y el detalle en `errors.error` o `error`: revise el cuerpo, no solo el código.", "content": { "application/json": { "example": { "resultado": true, "id_cliente": 45, "id_sucursal": 12, "mensaje": "cliente creado o actualizado" } } } } } } }, "/crear/productos": { "post": { "tags": [ "Emisión directa (api_key)" ], "operationId": "clasica_crear_productos", "x-azur-visibilidad": "publico", "summary": "Crear productos con stock inicial", "description": "Cada item: nombre, precio_unitario, tipoproducto (1 bien · 2 servicio), tipo_iva, id_bodega e id_categoria obligatorios; codigo_principal, codigo_auxiliar, stock, stock_inicial y costo_unitario opcionales.", "security": [ { "api_key_emision": [] }, [] ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "api_key": "API_…", "items": [ { "codigo_principal": "PROD-001", "nombre": "Laptop HP 15", "precio_unitario": 850, "tipoproducto": 1, "tipo_iva": 4, "stock_inicial": 10, "costo_unitario": 600, "id_bodega": 1, "id_categoria": 1 } ] } } } }, "responses": { "200": { "description": "Correcto. Los rechazos (api_key inexistente, validación) también llegan con HTTP 200 y el detalle en `errors.error` o `error`: revise el cuerpo, no solo el código.", "content": { "application/json": { "example": { "creado": true } } } } } } }, "/actualizar/productos": { "post": { "tags": [ "Emisión directa (api_key)" ], "operationId": "clasica_actualizar_productos", "x-azur-visibilidad": "publico", "summary": "Actualizar nombre y descripción de productos", "description": "Busca cada item por codigo_principal y actualiza nombre, descripcion y codigo_auxiliar.", "security": [ { "api_key_emision": [] }, [] ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "api_key": "API_…", "items": [ { "codigo_principal": "PROD-001", "nombre": "Laptop HP 15 (2026)", "descripcion": "Core i5, 16 GB", "codigo_auxiliar": "AUX-001" } ] } } } }, "responses": { "200": { "description": "Correcto. Los rechazos (api_key inexistente, validación) también llegan con HTTP 200 y el detalle en `errors.error` o `error`: revise el cuerpo, no solo el código.", "content": { "application/json": { "example": { "respuesta": true } } } } } } }, "/productos/obtenerstock": { "post": { "tags": [ "Emisión directa (api_key)" ], "operationId": "clasica_obtener_stock", "x-azur-visibilidad": "publico", "summary": "Consultar el stock de un producto", "description": "**Ojo:** este endpoint recibe la clave en el campo `api_key_empresa` del cuerpo (la cabecera X-Api-Key no aplica aquí).", "security": [ [] ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "api_key_empresa": "API_…", "codigo_establecimiento": "001", "codigo_producto": "PROD-001", "id_bodega": 1 } } } }, "responses": { "200": { "description": "Correcto. Los rechazos (api_key inexistente, validación) también llegan con HTTP 200 y el detalle en `errors.error` o `error`: revise el cuerpo, no solo el código.", "content": { "application/json": { "example": { "respuesta": true, "producto": "Laptop HP", "precio": 850, "cantidad": 12, "bodega": "Principal" } } } } } } }, "/consulta/comprobante": { "post": { "tags": [ "Emisión directa (api_key)" ], "operationId": "clasica_consulta_comprobante", "x-azur-visibilidad": "publico", "summary": "Consultar estado y enlaces PDF/XML", "description": "Estado del comprobante en el SRI (4 = autorizado, 9 = anulado…), número y, si está autorizado, los enlaces al PDF y al XML.", "security": [ { "api_key_emision": [] }, [] ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "api_key": "API_…", "claveacceso": "0110202601179999999900110010010000001231234567817" } } } }, "responses": { "200": { "description": "Correcto. Los rechazos (api_key inexistente, validación) también llegan con HTTP 200 y el detalle en `errors.error` o `error`: revise el cuerpo, no solo el código.", "content": { "application/json": { "example": { "creado": true, "claveacceso": "0110202601179999999900110010010000001231234567817", "estado": 4, "estado_texto": "Autorizado", "secuencial": "001-001-000000123", "fecha_aprobado": "2026-10-01 10:15:02", "enlace_pdf": "https://…", "enlace_xml": "https://…" } } } } } } }, "/consultar/comprobantes": { "post": { "tags": [ "Emisión directa (api_key)" ], "operationId": "clasica_consultar_cupo", "x-azur-visibilidad": "publico", "summary": "Comprobantes usados y restantes del plan", "description": "Plan vigente de la cuenta, comprobantes usados y los que quedan (-1 = ilimitado). **Obligatorio:** `usuario_principal`, el usuario con el que entra el dueño de la cuenta (no el de un vendedor).", "security": [ { "api_key_emision": [] }, [] ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "api_key": "API_…", "usuario_principal": "miusuario" } } } }, "responses": { "200": { "description": "Correcto. Los rechazos (api_key inexistente, validación) también llegan con HTTP 200 y el detalle en `errors.error` o `error`: revise el cuerpo, no solo el código.", "content": { "application/json": { "example": { "creado": true, "plan_actual": "Ilimitado", "comprobantes_utilizados": 340, "comprobantes_restantes": -1 } } } } } } }, "/enviar/correo": { "post": { "tags": [ "Emisión directa (api_key)" ], "operationId": "clasica_reenviar_correo", "x-azur-visibilidad": "publico", "summary": "Reenviar el comprobante por correo", "description": "**Ojo:** este endpoint recibe todo dentro de `notificacion` (incluida la clave en `notificacion.apikey`); la cabecera X-Api-Key no aplica aquí.", "security": [ [] ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "notificacion": { "apikey": "API_…", "claveacceso": "0110202601179999999900110010010000001231234567817", "motivo": "Reenvío solicitado por el cliente" } } } } }, "responses": { "200": { "description": "Correcto. Los rechazos (api_key inexistente, validación) también llegan con HTTP 200 y el detalle en `errors.error` o `error`: revise el cuerpo, no solo el código.", "content": { "application/json": { "example": { "respuesta": true } } } } } } }, "/factura/pagada": { "post": { "tags": [ "Emisión directa (api_key)" ], "operationId": "clasica_factura_pagada", "x-azur-visibilidad": "publico", "summary": "Marcar una factura como pagada", "description": "`pagada`: 1 = pagada, 0 = no pagada.", "security": [ { "api_key_emision": [] }, [] ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "api_key": "API_…", "claveacceso": "0110202601179999999900110010010000001231234567817", "pagada": 1 } } } }, "responses": { "200": { "description": "Correcto. Los rechazos (api_key inexistente, validación) también llegan con HTTP 200 y el detalle en `errors.error` o `error`: revise el cuerpo, no solo el código.", "content": { "application/json": { "example": { "modificado": true, "mensaje": "Correcto" } } } } } } }, "/factura/guardar": { "post": { "tags": [ "Comprobantes" ], "operationId": "guardar_factura", "summary": "Guardar Factura", "description": "Crea un Factura en AZUR.\n\nCon `accion: \"guardar\"` queda como **borrador**: no sale a ninguna parte y se puede revisar antes. Con `accion: \"enviar\"` se manda al SRI de inmediato.\n\nSi no está seguro de los datos, guarde primero como borrador y envíelo después: un comprobante que ya salió al SRI solo se puede corregir anulándolo.\n\nLos totales los calcula el servidor a partir de las líneas; no hace falta que los envíe.", "x-azur-visibilidad": "publico", "x-azur-tipo": "escritura", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Clave que usted inventa para esta operación. Si reintenta con la misma clave, se devuelve el resultado original en vez de crear un segundo documento. Se recuerda 24 horas. **Mándela siempre en lo que escriba**: si se corta la conexión, es lo único que evita el duplicado." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntradaDocumento" } } } }, "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Documento" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/factura/{id}": { "get": { "tags": [ "Comprobantes" ], "operationId": "ver_factura", "summary": "Consultar Factura", "description": "Devuelve un Factura con sus líneas y formas de pago. Use el `id` que devolvió al guardarlo.", "x-azur-visibilidad": "publico", "x-azur-tipo": "lectura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del documento en AZUR." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Documento" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } }, "put": { "tags": [ "Comprobantes" ], "operationId": "editar_factura", "summary": "Editar Factura", "description": "Reemplaza el contenido de un borrador: cabecera, líneas y formas de pago. Lo que mande sustituye a lo que había, no se mezcla.\n\n**Solo sobre borradores.** Un documento que ya salió al SRI devuelve `documento_no_editable`; para corregir uno emitido hay que anularlo y hacer otro. El número asignado no cambia al editar.", "x-azur-visibilidad": "publico", "x-azur-tipo": "escritura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del borrador." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntradaDocumento" } } } }, "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Documento" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } }, "delete": { "tags": [ "Comprobantes" ], "operationId": "eliminar_factura", "summary": "Eliminar Factura", "description": "Borra un documento que **nunca llegó a ser un comprobante**: el borrador que no se envió, o el que el SRI rechazó (no autorizado, error de secuencial, error al firmar). El secuencial queda libre.\n\nUn comprobante **autorizado no se borra: se anula** con `/anular`. Uno que está en la cola tampoco, porque el proceso lo tiene cogido.", "x-azur-visibilidad": "publico", "x-azur-tipo": "escritura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del documento." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Documento" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/facturas": { "get": { "tags": [ "Comprobantes" ], "operationId": "listar_factura", "summary": "Listar Factura", "description": "Lista los documentos de este tipo, del más reciente al más antiguo. Filtre por fechas o busque por número.\n\n**Por defecto solo los últimos 60 días.** Si no manda `desde`, `hasta` ni `buscar`, la lista se limita a los últimos 60 días —lo mismo que hace el portal en esa pantalla—, y `total` cuenta solo eso. La respuesta lo dice en `datos.ventana` (`aplicada`, `dias`, `desde`) y con un aviso en `avisos`. En cuanto mande una fecha o una búsqueda no se le limita nada: `ventana.aplicada` viene en `false`.\n\nCada fila trae `id`, `numero` —el completo, `EEE-PPP-SSSSSSSSS`—, `secuencial`, `fecha`, `total`, `estado` y **`cliente`**, con el nombre y la identificación de la contraparte. El nombre sale de la ficha viva; si esa ficha ya no existe, queda al menos la identificación que se grabó en el documento.", "x-azur-visibilidad": "publico", "x-azur-tipo": "lectura", "parameters": [ { "name": "desde", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Fecha de emisión desde (aaaa-mm-dd)." }, { "name": "hasta", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Fecha de emisión hasta (aaaa-mm-dd)." }, { "name": "buscar", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Parte del número del documento." }, { "name": "pagina", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Página, empezando en 1." }, { "name": "limite", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Cuántos por página, máximo 100." }, { "name": "modificado_desde", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Devuelve solo lo que CAMBIÓ desde ese momento (aaaa-mm-dd o aaaa-mm-dd hh:mm:ss), ordenado de más antiguo a más reciente. Es lo que hay que usar para sincronizar: a diferencia de «desde», que mira la fecha de emisión, esto sí devuelve una factura vieja que se acaba de anular o corregir." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Para seguir por donde se quedó. Se coge tal cual de «siguiente_cursor» de la llamada anterior; cuando venga vacío es que ya está al día. Con cursor NO se usa «pagina»: paginar por número se descoloca en cuanto entran documentos nuevos entre página y página." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Listado" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/factura/{id}/enviar": { "post": { "tags": [ "Comprobantes" ], "operationId": "enviar_factura", "summary": "Enviar Factura al SRI", "description": "Marca un borrador para que salga al SRI. AZUR genera el XML, lo firma y lo envía. **Solo funciona con documentos en estado borrador**: uno ya enviado devuelve `documento_no_editable`. Es irreversible: para deshacerlo hay que anular el comprobante.", "x-azur-visibilidad": "publico", "x-azur-tipo": "escritura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del documento." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Clave que usted inventa para esta operación. Si reintenta con la misma clave, se devuelve el resultado original en vez de crear un segundo documento. Se recuerda 24 horas. **Mándela siempre en lo que escriba**: si se corta la conexión, es lo único que evita el duplicado." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Documento" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/factura/{id}/estado": { "get": { "tags": [ "Comprobantes" ], "operationId": "estado_factura", "summary": "Estado de Factura", "description": "En qué punto del camino está el documento, con el **código numérico** del estado -que es con lo que se ramifica un flujo y no cambia nunca-, lo que contestó el SRI si lo rechazó, y qué hacer.\n\nCon `sri=1` además se le pregunta al SRI en directo, que es la única forma de enterarse si alguien anuló el comprobante desde SRI en línea.", "x-azur-visibilidad": "publico", "x-azur-tipo": "lectura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del documento." }, { "name": "sri", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "A 1 para consultar también al SRI en directo (tarda unos segundos)." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Documento" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/factura/{id}/anular": { "post": { "tags": [ "Comprobantes" ], "operationId": "anular_factura", "summary": "Anular Factura", "description": "**AZUR no anula en el SRI.** La solicitud de anulación la presenta el contribuyente en SRI en línea (Facturación Electrónica → Producción → Anulación). Lo que hace este endpoint es preguntarle al SRI si ese comprobante ya consta anulado y, si consta, darlo de baja también en AZUR: revierte el stock, el asiento contable y la cartera.\n\nSi la solicitud todavía no se ha presentado responde `anulacion_no_solicitada`; si pasó el plazo del SRI, `anulacion_fuera_de_plazo`. No anula una factura con pagos registrados, con notas de crédito vivas o con el asiento bloqueado: son las mismas guardas que el portal.", "x-azur-visibilidad": "publico", "x-azur-tipo": "escritura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del documento." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Clave que usted inventa para esta operación. Si reintenta con la misma clave, se devuelve el resultado original en vez de crear un segundo documento. Se recuerda 24 horas. **Mándela siempre en lo que escriba**: si se corta la conexión, es lo único que evita el duplicado." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Documento" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/factura/{id}/reprocesar": { "post": { "tags": [ "Comprobantes" ], "operationId": "reprocesar_factura", "summary": "Reprocesar Factura", "description": "Vuelve a meter en la cola un documento que se quedó parado -no autorizado, error de secuencial, error al firmar, SRI no disponible-: se regenera el XML, se firma y se reenvía.\n\nNo sirve para un documento ya autorizado, ni para un borrador (ése se manda con `/enviar`), ni para «establecimiento cerrado», que es configuración del emisor en el SRI y no se arregla reintentando.", "x-azur-visibilidad": "publico", "x-azur-tipo": "escritura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del documento." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Clave que usted inventa para esta operación. Si reintenta con la misma clave, se devuelve el resultado original en vez de crear un segundo documento. Se recuerda 24 horas. **Mándela siempre en lo que escriba**: si se corta la conexión, es lo único que evita el duplicado." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Documento" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/factura/{id}/correo": { "post": { "tags": [ "Comprobantes" ], "operationId": "correo_factura", "summary": "Reenviar Factura por correo", "description": "Reenvía el documento por correo con el PDF y el XML adjuntos, igual que el envío automático. Sin `correo` en el cuerpo va a los destinatarios que ya tiene el documento.", "x-azur-visibilidad": "publico", "x-azur-tipo": "escritura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del documento." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "correo": { "type": "string", "description": "A quién mandarlo. Si no se pone, a los correos del documento." } } } } } }, "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Documento" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/factura/{id}/pdf": { "get": { "tags": [ "Comprobantes" ], "operationId": "pdf_factura", "summary": "PDF de Factura", "description": "Devuelve el PDF (RIDE) del documento. **Solo existe una vez enviado al SRI**: un borrador todavía no tiene clave de acceso. Si el fichero se perdió, se regenera. Con `base64=1` viaja dentro del JSON de siempre.", "x-azur-visibilidad": "publico", "x-azur-tipo": "lectura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del documento." }, { "name": "base64", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "A 1 para recibirlo dentro del JSON." } ], "responses": { "200": { "description": "El fichero. Con `base64=1`, el JSON de siempre.", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Archivo" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta, o el fichero todavía no existe.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta, o el fichero todavía no existe.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/factura/{id}/xml": { "get": { "tags": [ "Comprobantes" ], "operationId": "xml_factura", "summary": "XML de Factura", "description": "Devuelve el XML **autorizado** por el SRI, que es el que tiene valor tributario y el único que se conserva. Con `tipo=firmado` devuelve el que se envió, extraído de dentro del autorizado. Solo existe si el SRI ya autorizó.", "x-azur-visibilidad": "publico", "x-azur-tipo": "lectura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del documento." }, { "name": "tipo", "in": "query", "required": false, "schema": { "type": "string" }, "description": "`autorizado` (por defecto) o `firmado`." }, { "name": "base64", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "A 1 para recibirlo dentro del JSON." } ], "responses": { "200": { "description": "El fichero. Con `base64=1`, el JSON de siempre.", "content": { "application/xml": { "schema": { "type": "string", "format": "binary" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Archivo" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta, o el fichero todavía no existe.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta, o el fichero todavía no existe.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/credito/guardar": { "post": { "tags": [ "Comprobantes" ], "operationId": "guardar_credito", "summary": "Guardar Nota de crédito", "description": "Crea un Nota de crédito en AZUR.\n\nCon `accion: \"guardar\"` queda como **borrador**: no sale a ninguna parte y se puede revisar antes. Con `accion: \"enviar\"` se manda al SRI de inmediato.\n\nSi no está seguro de los datos, guarde primero como borrador y envíelo después: un comprobante que ya salió al SRI solo se puede corregir anulándolo.\n\nLos totales los calcula el servidor a partir de las líneas; no hace falta que los envíe.", "x-azur-visibilidad": "publico", "x-azur-tipo": "escritura", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Clave que usted inventa para esta operación. Si reintenta con la misma clave, se devuelve el resultado original en vez de crear un segundo documento. Se recuerda 24 horas. **Mándela siempre en lo que escriba**: si se corta la conexión, es lo único que evita el duplicado." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntradaCredito" } } } }, "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Documento" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/credito/{id}": { "get": { "tags": [ "Comprobantes" ], "operationId": "ver_credito", "summary": "Consultar Nota de crédito", "description": "Devuelve un Nota de crédito con sus líneas y formas de pago. Use el `id` que devolvió al guardarlo.", "x-azur-visibilidad": "publico", "x-azur-tipo": "lectura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del documento en AZUR." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Documento" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } }, "put": { "tags": [ "Comprobantes" ], "operationId": "editar_credito", "summary": "Editar Nota de crédito", "description": "Reemplaza el contenido de un borrador: cabecera, líneas y formas de pago. Lo que mande sustituye a lo que había, no se mezcla.\n\n**Solo sobre borradores.** Un documento que ya salió al SRI devuelve `documento_no_editable`; para corregir uno emitido hay que anularlo y hacer otro. El número asignado no cambia al editar.", "x-azur-visibilidad": "publico", "x-azur-tipo": "escritura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del borrador." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntradaCredito" } } } }, "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Documento" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } }, "delete": { "tags": [ "Comprobantes" ], "operationId": "eliminar_credito", "summary": "Eliminar Nota de crédito", "description": "Borra un documento que **nunca llegó a ser un comprobante**: el borrador que no se envió, o el que el SRI rechazó (no autorizado, error de secuencial, error al firmar). El secuencial queda libre.\n\nUn comprobante **autorizado no se borra: se anula** con `/anular`. Uno que está en la cola tampoco, porque el proceso lo tiene cogido.", "x-azur-visibilidad": "publico", "x-azur-tipo": "escritura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del documento." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Documento" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/creditos": { "get": { "tags": [ "Comprobantes" ], "operationId": "listar_credito", "summary": "Listar Nota de crédito", "description": "Lista los documentos de este tipo, del más reciente al más antiguo. Filtre por fechas o busque por número.\n\n**Por defecto solo los últimos 60 días.** Si no manda `desde`, `hasta` ni `buscar`, la lista se limita a los últimos 60 días —lo mismo que hace el portal en esa pantalla—, y `total` cuenta solo eso. La respuesta lo dice en `datos.ventana` (`aplicada`, `dias`, `desde`) y con un aviso en `avisos`. En cuanto mande una fecha o una búsqueda no se le limita nada: `ventana.aplicada` viene en `false`.\n\nCada fila trae `id`, `numero` —el completo, `EEE-PPP-SSSSSSSSS`—, `secuencial`, `fecha`, `total`, `estado` y **`cliente`**, con el nombre y la identificación de la contraparte. El nombre sale de la ficha viva; si esa ficha ya no existe, queda al menos la identificación que se grabó en el documento.", "x-azur-visibilidad": "publico", "x-azur-tipo": "lectura", "parameters": [ { "name": "desde", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Fecha de emisión desde (aaaa-mm-dd)." }, { "name": "hasta", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Fecha de emisión hasta (aaaa-mm-dd)." }, { "name": "buscar", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Parte del número del documento." }, { "name": "pagina", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Página, empezando en 1." }, { "name": "limite", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Cuántos por página, máximo 100." }, { "name": "modificado_desde", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Devuelve solo lo que CAMBIÓ desde ese momento (aaaa-mm-dd o aaaa-mm-dd hh:mm:ss), ordenado de más antiguo a más reciente. Es lo que hay que usar para sincronizar: a diferencia de «desde», que mira la fecha de emisión, esto sí devuelve una factura vieja que se acaba de anular o corregir." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Para seguir por donde se quedó. Se coge tal cual de «siguiente_cursor» de la llamada anterior; cuando venga vacío es que ya está al día. Con cursor NO se usa «pagina»: paginar por número se descoloca en cuanto entran documentos nuevos entre página y página." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Listado" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/credito/{id}/enviar": { "post": { "tags": [ "Comprobantes" ], "operationId": "enviar_credito", "summary": "Enviar Nota de crédito al SRI", "description": "Marca un borrador para que salga al SRI. AZUR genera el XML, lo firma y lo envía. **Solo funciona con documentos en estado borrador**: uno ya enviado devuelve `documento_no_editable`. Es irreversible: para deshacerlo hay que anular el comprobante.", "x-azur-visibilidad": "publico", "x-azur-tipo": "escritura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del documento." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Clave que usted inventa para esta operación. Si reintenta con la misma clave, se devuelve el resultado original en vez de crear un segundo documento. Se recuerda 24 horas. **Mándela siempre en lo que escriba**: si se corta la conexión, es lo único que evita el duplicado." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Documento" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/credito/{id}/estado": { "get": { "tags": [ "Comprobantes" ], "operationId": "estado_credito", "summary": "Estado de Nota de crédito", "description": "En qué punto del camino está el documento, con el **código numérico** del estado -que es con lo que se ramifica un flujo y no cambia nunca-, lo que contestó el SRI si lo rechazó, y qué hacer.\n\nCon `sri=1` además se le pregunta al SRI en directo, que es la única forma de enterarse si alguien anuló el comprobante desde SRI en línea.", "x-azur-visibilidad": "publico", "x-azur-tipo": "lectura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del documento." }, { "name": "sri", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "A 1 para consultar también al SRI en directo (tarda unos segundos)." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Documento" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/credito/{id}/anular": { "post": { "tags": [ "Comprobantes" ], "operationId": "anular_credito", "summary": "Anular Nota de crédito", "description": "**AZUR no anula en el SRI.** La solicitud de anulación la presenta el contribuyente en SRI en línea (Facturación Electrónica → Producción → Anulación). Lo que hace este endpoint es preguntarle al SRI si ese comprobante ya consta anulado y, si consta, darlo de baja también en AZUR: revierte el stock, el asiento contable y la cartera.\n\nSi la solicitud todavía no se ha presentado responde `anulacion_no_solicitada`; si pasó el plazo del SRI, `anulacion_fuera_de_plazo`. No anula una factura con pagos registrados, con notas de crédito vivas o con el asiento bloqueado: son las mismas guardas que el portal.", "x-azur-visibilidad": "publico", "x-azur-tipo": "escritura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del documento." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Clave que usted inventa para esta operación. Si reintenta con la misma clave, se devuelve el resultado original en vez de crear un segundo documento. Se recuerda 24 horas. **Mándela siempre en lo que escriba**: si se corta la conexión, es lo único que evita el duplicado." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Documento" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/credito/{id}/reprocesar": { "post": { "tags": [ "Comprobantes" ], "operationId": "reprocesar_credito", "summary": "Reprocesar Nota de crédito", "description": "Vuelve a meter en la cola un documento que se quedó parado -no autorizado, error de secuencial, error al firmar, SRI no disponible-: se regenera el XML, se firma y se reenvía.\n\nNo sirve para un documento ya autorizado, ni para un borrador (ése se manda con `/enviar`), ni para «establecimiento cerrado», que es configuración del emisor en el SRI y no se arregla reintentando.", "x-azur-visibilidad": "publico", "x-azur-tipo": "escritura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del documento." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Clave que usted inventa para esta operación. Si reintenta con la misma clave, se devuelve el resultado original en vez de crear un segundo documento. Se recuerda 24 horas. **Mándela siempre en lo que escriba**: si se corta la conexión, es lo único que evita el duplicado." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Documento" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/credito/{id}/correo": { "post": { "tags": [ "Comprobantes" ], "operationId": "correo_credito", "summary": "Reenviar Nota de crédito por correo", "description": "Reenvía el documento por correo con el PDF y el XML adjuntos, igual que el envío automático. Sin `correo` en el cuerpo va a los destinatarios que ya tiene el documento.", "x-azur-visibilidad": "publico", "x-azur-tipo": "escritura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del documento." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "correo": { "type": "string", "description": "A quién mandarlo. Si no se pone, a los correos del documento." } } } } } }, "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Documento" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/credito/{id}/pdf": { "get": { "tags": [ "Comprobantes" ], "operationId": "pdf_credito", "summary": "PDF de Nota de crédito", "description": "Devuelve el PDF (RIDE) del documento. **Solo existe una vez enviado al SRI**: un borrador todavía no tiene clave de acceso. Si el fichero se perdió, se regenera. Con `base64=1` viaja dentro del JSON de siempre.", "x-azur-visibilidad": "publico", "x-azur-tipo": "lectura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del documento." }, { "name": "base64", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "A 1 para recibirlo dentro del JSON." } ], "responses": { "200": { "description": "El fichero. Con `base64=1`, el JSON de siempre.", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Archivo" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta, o el fichero todavía no existe.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta, o el fichero todavía no existe.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/credito/{id}/xml": { "get": { "tags": [ "Comprobantes" ], "operationId": "xml_credito", "summary": "XML de Nota de crédito", "description": "Devuelve el XML **autorizado** por el SRI, que es el que tiene valor tributario y el único que se conserva. Con `tipo=firmado` devuelve el que se envió, extraído de dentro del autorizado. Solo existe si el SRI ya autorizó.", "x-azur-visibilidad": "publico", "x-azur-tipo": "lectura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del documento." }, { "name": "tipo", "in": "query", "required": false, "schema": { "type": "string" }, "description": "`autorizado` (por defecto) o `firmado`." }, { "name": "base64", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "A 1 para recibirlo dentro del JSON." } ], "responses": { "200": { "description": "El fichero. Con `base64=1`, el JSON de siempre.", "content": { "application/xml": { "schema": { "type": "string", "format": "binary" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Archivo" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta, o el fichero todavía no existe.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta, o el fichero todavía no existe.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/debito/guardar": { "post": { "tags": [ "Comprobantes" ], "operationId": "guardar_debito", "summary": "Guardar Nota de débito", "description": "Crea un Nota de débito en AZUR.\n\nCon `accion: \"guardar\"` queda como **borrador**: no sale a ninguna parte y se puede revisar antes. Con `accion: \"enviar\"` se manda al SRI de inmediato.\n\nSi no está seguro de los datos, guarde primero como borrador y envíelo después: un comprobante que ya salió al SRI solo se puede corregir anulándolo.\n\nLos totales los calcula el servidor a partir de las líneas; no hace falta que los envíe.\n\n**No se puede editar** después de creado.", "x-azur-visibilidad": "publico", "x-azur-tipo": "escritura", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Clave que usted inventa para esta operación. Si reintenta con la misma clave, se devuelve el resultado original en vez de crear un segundo documento. Se recuerda 24 horas. **Mándela siempre en lo que escriba**: si se corta la conexión, es lo único que evita el duplicado." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntradaDebito" } } } }, "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Documento" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/debito/{id}": { "get": { "tags": [ "Comprobantes" ], "operationId": "ver_debito", "summary": "Consultar Nota de débito", "description": "Devuelve un Nota de débito con sus líneas y formas de pago. Use el `id` que devolvió al guardarlo.", "x-azur-visibilidad": "publico", "x-azur-tipo": "lectura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del documento en AZUR." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Documento" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } }, "delete": { "tags": [ "Comprobantes" ], "operationId": "eliminar_debito", "summary": "Eliminar Nota de débito", "description": "Borra un documento que **nunca llegó a ser un comprobante**: el borrador que no se envió, o el que el SRI rechazó (no autorizado, error de secuencial, error al firmar). El secuencial queda libre.\n\nUn comprobante **autorizado no se borra: se anula** con `/anular`. Uno que está en la cola tampoco, porque el proceso lo tiene cogido.", "x-azur-visibilidad": "publico", "x-azur-tipo": "escritura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del documento." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Documento" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/debitos": { "get": { "tags": [ "Comprobantes" ], "operationId": "listar_debito", "summary": "Listar Nota de débito", "description": "Lista los documentos de este tipo, del más reciente al más antiguo. Filtre por fechas o busque por número.\n\n**Por defecto solo los últimos 60 días.** Si no manda `desde`, `hasta` ni `buscar`, la lista se limita a los últimos 60 días —lo mismo que hace el portal en esa pantalla—, y `total` cuenta solo eso. La respuesta lo dice en `datos.ventana` (`aplicada`, `dias`, `desde`) y con un aviso en `avisos`. En cuanto mande una fecha o una búsqueda no se le limita nada: `ventana.aplicada` viene en `false`.\n\nCada fila trae `id`, `numero` —el completo, `EEE-PPP-SSSSSSSSS`—, `secuencial`, `fecha`, `total`, `estado` y **`cliente`**, con el nombre y la identificación de la contraparte. El nombre sale de la ficha viva; si esa ficha ya no existe, queda al menos la identificación que se grabó en el documento.", "x-azur-visibilidad": "publico", "x-azur-tipo": "lectura", "parameters": [ { "name": "desde", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Fecha de emisión desde (aaaa-mm-dd)." }, { "name": "hasta", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Fecha de emisión hasta (aaaa-mm-dd)." }, { "name": "buscar", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Parte del número del documento." }, { "name": "pagina", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Página, empezando en 1." }, { "name": "limite", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Cuántos por página, máximo 100." }, { "name": "modificado_desde", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Devuelve solo lo que CAMBIÓ desde ese momento (aaaa-mm-dd o aaaa-mm-dd hh:mm:ss), ordenado de más antiguo a más reciente. Es lo que hay que usar para sincronizar: a diferencia de «desde», que mira la fecha de emisión, esto sí devuelve una factura vieja que se acaba de anular o corregir." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Para seguir por donde se quedó. Se coge tal cual de «siguiente_cursor» de la llamada anterior; cuando venga vacío es que ya está al día. Con cursor NO se usa «pagina»: paginar por número se descoloca en cuanto entran documentos nuevos entre página y página." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Listado" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/debito/{id}/enviar": { "post": { "tags": [ "Comprobantes" ], "operationId": "enviar_debito", "summary": "Enviar Nota de débito al SRI", "description": "Marca un borrador para que salga al SRI. AZUR genera el XML, lo firma y lo envía. **Solo funciona con documentos en estado borrador**: uno ya enviado devuelve `documento_no_editable`. Es irreversible: para deshacerlo hay que anular el comprobante.", "x-azur-visibilidad": "publico", "x-azur-tipo": "escritura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del documento." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Clave que usted inventa para esta operación. Si reintenta con la misma clave, se devuelve el resultado original en vez de crear un segundo documento. Se recuerda 24 horas. **Mándela siempre en lo que escriba**: si se corta la conexión, es lo único que evita el duplicado." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Documento" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/debito/{id}/estado": { "get": { "tags": [ "Comprobantes" ], "operationId": "estado_debito", "summary": "Estado de Nota de débito", "description": "En qué punto del camino está el documento, con el **código numérico** del estado -que es con lo que se ramifica un flujo y no cambia nunca-, lo que contestó el SRI si lo rechazó, y qué hacer.\n\nCon `sri=1` además se le pregunta al SRI en directo, que es la única forma de enterarse si alguien anuló el comprobante desde SRI en línea.", "x-azur-visibilidad": "publico", "x-azur-tipo": "lectura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del documento." }, { "name": "sri", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "A 1 para consultar también al SRI en directo (tarda unos segundos)." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Documento" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/debito/{id}/anular": { "post": { "tags": [ "Comprobantes" ], "operationId": "anular_debito", "summary": "Anular Nota de débito", "description": "**AZUR no anula en el SRI.** La solicitud de anulación la presenta el contribuyente en SRI en línea (Facturación Electrónica → Producción → Anulación). Lo que hace este endpoint es preguntarle al SRI si ese comprobante ya consta anulado y, si consta, darlo de baja también en AZUR: revierte el stock, el asiento contable y la cartera.\n\nSi la solicitud todavía no se ha presentado responde `anulacion_no_solicitada`; si pasó el plazo del SRI, `anulacion_fuera_de_plazo`. No anula una factura con pagos registrados, con notas de crédito vivas o con el asiento bloqueado: son las mismas guardas que el portal.", "x-azur-visibilidad": "publico", "x-azur-tipo": "escritura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del documento." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Clave que usted inventa para esta operación. Si reintenta con la misma clave, se devuelve el resultado original en vez de crear un segundo documento. Se recuerda 24 horas. **Mándela siempre en lo que escriba**: si se corta la conexión, es lo único que evita el duplicado." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Documento" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/debito/{id}/reprocesar": { "post": { "tags": [ "Comprobantes" ], "operationId": "reprocesar_debito", "summary": "Reprocesar Nota de débito", "description": "Vuelve a meter en la cola un documento que se quedó parado -no autorizado, error de secuencial, error al firmar, SRI no disponible-: se regenera el XML, se firma y se reenvía.\n\nNo sirve para un documento ya autorizado, ni para un borrador (ése se manda con `/enviar`), ni para «establecimiento cerrado», que es configuración del emisor en el SRI y no se arregla reintentando.", "x-azur-visibilidad": "publico", "x-azur-tipo": "escritura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del documento." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Clave que usted inventa para esta operación. Si reintenta con la misma clave, se devuelve el resultado original en vez de crear un segundo documento. Se recuerda 24 horas. **Mándela siempre en lo que escriba**: si se corta la conexión, es lo único que evita el duplicado." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Documento" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/debito/{id}/correo": { "post": { "tags": [ "Comprobantes" ], "operationId": "correo_debito", "summary": "Reenviar Nota de débito por correo", "description": "Reenvía el documento por correo con el PDF y el XML adjuntos, igual que el envío automático. Sin `correo` en el cuerpo va a los destinatarios que ya tiene el documento.", "x-azur-visibilidad": "publico", "x-azur-tipo": "escritura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del documento." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "correo": { "type": "string", "description": "A quién mandarlo. Si no se pone, a los correos del documento." } } } } } }, "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Documento" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/debito/{id}/pdf": { "get": { "tags": [ "Comprobantes" ], "operationId": "pdf_debito", "summary": "PDF de Nota de débito", "description": "Devuelve el PDF (RIDE) del documento. **Solo existe una vez enviado al SRI**: un borrador todavía no tiene clave de acceso. Si el fichero se perdió, se regenera. Con `base64=1` viaja dentro del JSON de siempre.", "x-azur-visibilidad": "publico", "x-azur-tipo": "lectura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del documento." }, { "name": "base64", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "A 1 para recibirlo dentro del JSON." } ], "responses": { "200": { "description": "El fichero. Con `base64=1`, el JSON de siempre.", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Archivo" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta, o el fichero todavía no existe.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta, o el fichero todavía no existe.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/debito/{id}/xml": { "get": { "tags": [ "Comprobantes" ], "operationId": "xml_debito", "summary": "XML de Nota de débito", "description": "Devuelve el XML **autorizado** por el SRI, que es el que tiene valor tributario y el único que se conserva. Con `tipo=firmado` devuelve el que se envió, extraído de dentro del autorizado. Solo existe si el SRI ya autorizó.", "x-azur-visibilidad": "publico", "x-azur-tipo": "lectura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del documento." }, { "name": "tipo", "in": "query", "required": false, "schema": { "type": "string" }, "description": "`autorizado` (por defecto) o `firmado`." }, { "name": "base64", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "A 1 para recibirlo dentro del JSON." } ], "responses": { "200": { "description": "El fichero. Con `base64=1`, el JSON de siempre.", "content": { "application/xml": { "schema": { "type": "string", "format": "binary" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Archivo" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta, o el fichero todavía no existe.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta, o el fichero todavía no existe.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/guia/guardar": { "post": { "tags": [ "Comprobantes" ], "operationId": "guardar_guia", "summary": "Guardar Guía de remisión", "description": "Crea un Guía de remisión en AZUR.\n\nCon `accion: \"guardar\"` queda como **borrador**: no sale a ninguna parte y se puede revisar antes. Con `accion: \"enviar\"` se manda al SRI de inmediato.\n\nSi no está seguro de los datos, guarde primero como borrador y envíelo después: un comprobante que ya salió al SRI solo se puede corregir anulándolo.\n\nLos totales los calcula el servidor a partir de las líneas; no hace falta que los envíe.", "x-azur-visibilidad": "publico", "x-azur-tipo": "escritura", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Clave que usted inventa para esta operación. Si reintenta con la misma clave, se devuelve el resultado original en vez de crear un segundo documento. Se recuerda 24 horas. **Mándela siempre en lo que escriba**: si se corta la conexión, es lo único que evita el duplicado." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntradaGuia" } } } }, "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Documento" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/guia/{id}": { "get": { "tags": [ "Comprobantes" ], "operationId": "ver_guia", "summary": "Consultar Guía de remisión", "description": "Devuelve un Guía de remisión con sus líneas y formas de pago. Use el `id` que devolvió al guardarlo.", "x-azur-visibilidad": "publico", "x-azur-tipo": "lectura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del documento en AZUR." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Documento" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } }, "put": { "tags": [ "Comprobantes" ], "operationId": "editar_guia", "summary": "Editar Guía de remisión", "description": "Reemplaza el contenido de un borrador: cabecera, líneas y formas de pago. Lo que mande sustituye a lo que había, no se mezcla.\n\n**Solo sobre borradores.** Un documento que ya salió al SRI devuelve `documento_no_editable`; para corregir uno emitido hay que anularlo y hacer otro. El número asignado no cambia al editar.", "x-azur-visibilidad": "publico", "x-azur-tipo": "escritura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del borrador." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntradaGuia" } } } }, "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Documento" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } }, "delete": { "tags": [ "Comprobantes" ], "operationId": "eliminar_guia", "summary": "Eliminar Guía de remisión", "description": "Borra un documento que **nunca llegó a ser un comprobante**: el borrador que no se envió, o el que el SRI rechazó (no autorizado, error de secuencial, error al firmar). El secuencial queda libre.\n\nUn comprobante **autorizado no se borra: se anula** con `/anular`. Uno que está en la cola tampoco, porque el proceso lo tiene cogido.", "x-azur-visibilidad": "publico", "x-azur-tipo": "escritura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del documento." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Documento" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/guias": { "get": { "tags": [ "Comprobantes" ], "operationId": "listar_guia", "summary": "Listar Guía de remisión", "description": "Lista los documentos de este tipo, del más reciente al más antiguo. Filtre por fechas o busque por número.\n\n**Por defecto solo los últimos 60 días.** Si no manda `desde`, `hasta` ni `buscar`, la lista se limita a los últimos 60 días —lo mismo que hace el portal en esa pantalla—, y `total` cuenta solo eso. La respuesta lo dice en `datos.ventana` (`aplicada`, `dias`, `desde`) y con un aviso en `avisos`. En cuanto mande una fecha o una búsqueda no se le limita nada: `ventana.aplicada` viene en `false`.\n\nCada fila trae `id`, `numero` —el completo, `EEE-PPP-SSSSSSSSS`—, `secuencial`, `fecha`, `total`, `estado` y **`cliente`**, con el nombre y la identificación de la contraparte. El nombre sale de la ficha viva; si esa ficha ya no existe, queda al menos la identificación que se grabó en el documento.", "x-azur-visibilidad": "publico", "x-azur-tipo": "lectura", "parameters": [ { "name": "desde", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Fecha de emisión desde (aaaa-mm-dd)." }, { "name": "hasta", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Fecha de emisión hasta (aaaa-mm-dd)." }, { "name": "buscar", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Parte del número del documento." }, { "name": "pagina", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Página, empezando en 1." }, { "name": "limite", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Cuántos por página, máximo 100." }, { "name": "modificado_desde", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Devuelve solo lo que CAMBIÓ desde ese momento (aaaa-mm-dd o aaaa-mm-dd hh:mm:ss), ordenado de más antiguo a más reciente. Es lo que hay que usar para sincronizar: a diferencia de «desde», que mira la fecha de emisión, esto sí devuelve una factura vieja que se acaba de anular o corregir." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Para seguir por donde se quedó. Se coge tal cual de «siguiente_cursor» de la llamada anterior; cuando venga vacío es que ya está al día. Con cursor NO se usa «pagina»: paginar por número se descoloca en cuanto entran documentos nuevos entre página y página." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Listado" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/guia/{id}/enviar": { "post": { "tags": [ "Comprobantes" ], "operationId": "enviar_guia", "summary": "Enviar Guía de remisión al SRI", "description": "Marca un borrador para que salga al SRI. AZUR genera el XML, lo firma y lo envía. **Solo funciona con documentos en estado borrador**: uno ya enviado devuelve `documento_no_editable`. Es irreversible: para deshacerlo hay que anular el comprobante.", "x-azur-visibilidad": "publico", "x-azur-tipo": "escritura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del documento." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Clave que usted inventa para esta operación. Si reintenta con la misma clave, se devuelve el resultado original en vez de crear un segundo documento. Se recuerda 24 horas. **Mándela siempre en lo que escriba**: si se corta la conexión, es lo único que evita el duplicado." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Documento" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/guia/{id}/estado": { "get": { "tags": [ "Comprobantes" ], "operationId": "estado_guia", "summary": "Estado de Guía de remisión", "description": "En qué punto del camino está el documento, con el **código numérico** del estado -que es con lo que se ramifica un flujo y no cambia nunca-, lo que contestó el SRI si lo rechazó, y qué hacer.\n\nCon `sri=1` además se le pregunta al SRI en directo, que es la única forma de enterarse si alguien anuló el comprobante desde SRI en línea.", "x-azur-visibilidad": "publico", "x-azur-tipo": "lectura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del documento." }, { "name": "sri", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "A 1 para consultar también al SRI en directo (tarda unos segundos)." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Documento" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/guia/{id}/anular": { "post": { "tags": [ "Comprobantes" ], "operationId": "anular_guia", "summary": "Anular Guía de remisión", "description": "**AZUR no anula en el SRI.** La solicitud de anulación la presenta el contribuyente en SRI en línea (Facturación Electrónica → Producción → Anulación). Lo que hace este endpoint es preguntarle al SRI si ese comprobante ya consta anulado y, si consta, darlo de baja también en AZUR: revierte el stock, el asiento contable y la cartera.\n\nSi la solicitud todavía no se ha presentado responde `anulacion_no_solicitada`; si pasó el plazo del SRI, `anulacion_fuera_de_plazo`. No anula una factura con pagos registrados, con notas de crédito vivas o con el asiento bloqueado: son las mismas guardas que el portal.", "x-azur-visibilidad": "publico", "x-azur-tipo": "escritura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del documento." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Clave que usted inventa para esta operación. Si reintenta con la misma clave, se devuelve el resultado original en vez de crear un segundo documento. Se recuerda 24 horas. **Mándela siempre en lo que escriba**: si se corta la conexión, es lo único que evita el duplicado." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Documento" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/guia/{id}/reprocesar": { "post": { "tags": [ "Comprobantes" ], "operationId": "reprocesar_guia", "summary": "Reprocesar Guía de remisión", "description": "Vuelve a meter en la cola un documento que se quedó parado -no autorizado, error de secuencial, error al firmar, SRI no disponible-: se regenera el XML, se firma y se reenvía.\n\nNo sirve para un documento ya autorizado, ni para un borrador (ése se manda con `/enviar`), ni para «establecimiento cerrado», que es configuración del emisor en el SRI y no se arregla reintentando.", "x-azur-visibilidad": "publico", "x-azur-tipo": "escritura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del documento." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Clave que usted inventa para esta operación. Si reintenta con la misma clave, se devuelve el resultado original en vez de crear un segundo documento. Se recuerda 24 horas. **Mándela siempre en lo que escriba**: si se corta la conexión, es lo único que evita el duplicado." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Documento" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/guia/{id}/correo": { "post": { "tags": [ "Comprobantes" ], "operationId": "correo_guia", "summary": "Reenviar Guía de remisión por correo", "description": "Reenvía el documento por correo con el PDF y el XML adjuntos, igual que el envío automático. Sin `correo` en el cuerpo va a los destinatarios que ya tiene el documento.", "x-azur-visibilidad": "publico", "x-azur-tipo": "escritura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del documento." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "correo": { "type": "string", "description": "A quién mandarlo. Si no se pone, a los correos del documento." } } } } } }, "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Documento" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/guia/{id}/pdf": { "get": { "tags": [ "Comprobantes" ], "operationId": "pdf_guia", "summary": "PDF de Guía de remisión", "description": "Devuelve el PDF (RIDE) del documento. **Solo existe una vez enviado al SRI**: un borrador todavía no tiene clave de acceso. Si el fichero se perdió, se regenera. Con `base64=1` viaja dentro del JSON de siempre.", "x-azur-visibilidad": "publico", "x-azur-tipo": "lectura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del documento." }, { "name": "base64", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "A 1 para recibirlo dentro del JSON." } ], "responses": { "200": { "description": "El fichero. Con `base64=1`, el JSON de siempre.", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Archivo" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta, o el fichero todavía no existe.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta, o el fichero todavía no existe.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/guia/{id}/xml": { "get": { "tags": [ "Comprobantes" ], "operationId": "xml_guia", "summary": "XML de Guía de remisión", "description": "Devuelve el XML **autorizado** por el SRI, que es el que tiene valor tributario y el único que se conserva. Con `tipo=firmado` devuelve el que se envió, extraído de dentro del autorizado. Solo existe si el SRI ya autorizó.", "x-azur-visibilidad": "publico", "x-azur-tipo": "lectura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del documento." }, { "name": "tipo", "in": "query", "required": false, "schema": { "type": "string" }, "description": "`autorizado` (por defecto) o `firmado`." }, { "name": "base64", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "A 1 para recibirlo dentro del JSON." } ], "responses": { "200": { "description": "El fichero. Con `base64=1`, el JSON de siempre.", "content": { "application/xml": { "schema": { "type": "string", "format": "binary" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Archivo" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta, o el fichero todavía no existe.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta, o el fichero todavía no existe.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/retencion/guardar": { "post": { "tags": [ "Comprobantes" ], "operationId": "guardar_retencion", "summary": "Guardar Comprobante de retención", "description": "Crea un Comprobante de retención en AZUR.\n\nCon `accion: \"guardar\"` queda como **borrador**: no sale a ninguna parte y se puede revisar antes. Con `accion: \"enviar\"` se manda al SRI de inmediato.\n\nSi no está seguro de los datos, guarde primero como borrador y envíelo después: un comprobante que ya salió al SRI solo se puede corregir anulándolo.\n\nLos totales los calcula el servidor a partir de las líneas; no hace falta que los envíe.\n\n**No se puede editar** después de creado.", "x-azur-visibilidad": "publico", "x-azur-tipo": "escritura", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Clave que usted inventa para esta operación. Si reintenta con la misma clave, se devuelve el resultado original en vez de crear un segundo documento. Se recuerda 24 horas. **Mándela siempre en lo que escriba**: si se corta la conexión, es lo único que evita el duplicado." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntradaRetencion" } } } }, "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Documento" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/retencion/{id}": { "get": { "tags": [ "Comprobantes" ], "operationId": "ver_retencion", "summary": "Consultar Comprobante de retención", "description": "Devuelve un Comprobante de retención con sus líneas y formas de pago. Use el `id` que devolvió al guardarlo.", "x-azur-visibilidad": "publico", "x-azur-tipo": "lectura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del documento en AZUR." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Documento" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } }, "delete": { "tags": [ "Comprobantes" ], "operationId": "eliminar_retencion", "summary": "Eliminar Comprobante de retención", "description": "Borra un documento que **nunca llegó a ser un comprobante**: el borrador que no se envió, o el que el SRI rechazó (no autorizado, error de secuencial, error al firmar). El secuencial queda libre.\n\nUn comprobante **autorizado no se borra: se anula** con `/anular`. Uno que está en la cola tampoco, porque el proceso lo tiene cogido.", "x-azur-visibilidad": "publico", "x-azur-tipo": "escritura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del documento." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Documento" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/retenciones": { "get": { "tags": [ "Comprobantes" ], "operationId": "listar_retencion", "summary": "Listar Comprobante de retención", "description": "Lista los documentos de este tipo, del más reciente al más antiguo. Filtre por fechas o busque por número.\n\n**Por defecto solo los últimos 60 días.** Si no manda `desde`, `hasta` ni `buscar`, la lista se limita a los últimos 60 días —lo mismo que hace el portal en esa pantalla—, y `total` cuenta solo eso. La respuesta lo dice en `datos.ventana` (`aplicada`, `dias`, `desde`) y con un aviso en `avisos`. En cuanto mande una fecha o una búsqueda no se le limita nada: `ventana.aplicada` viene en `false`.\n\nCada fila trae `id`, `numero` —el completo, `EEE-PPP-SSSSSSSSS`—, `secuencial`, `fecha`, `total`, `estado` y **`cliente`**, con el nombre y la identificación de la contraparte. Aquí la contraparte es el **proveedor**, y así lo dice el campo `cliente.tipo`. El nombre sale de la ficha viva; si esa ficha ya no existe, queda al menos la identificación que se grabó en el documento.\n\nY trae `esquema` con su `id_compra`: `2.0.0` si la retención salió de una compra —que es lo que exige el SRI hoy— y `1.0.0` si se emitió suelta, sin compra vinculada.", "x-azur-visibilidad": "publico", "x-azur-tipo": "lectura", "parameters": [ { "name": "desde", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Fecha de emisión desde (aaaa-mm-dd)." }, { "name": "hasta", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Fecha de emisión hasta (aaaa-mm-dd)." }, { "name": "buscar", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Parte del número del documento." }, { "name": "pagina", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Página, empezando en 1." }, { "name": "limite", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Cuántos por página, máximo 100." }, { "name": "modificado_desde", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Devuelve solo lo que CAMBIÓ desde ese momento (aaaa-mm-dd o aaaa-mm-dd hh:mm:ss), ordenado de más antiguo a más reciente. Es lo que hay que usar para sincronizar: a diferencia de «desde», que mira la fecha de emisión, esto sí devuelve una factura vieja que se acaba de anular o corregir." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Para seguir por donde se quedó. Se coge tal cual de «siguiente_cursor» de la llamada anterior; cuando venga vacío es que ya está al día. Con cursor NO se usa «pagina»: paginar por número se descoloca en cuanto entran documentos nuevos entre página y página." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Listado" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/retencion/{id}/enviar": { "post": { "tags": [ "Comprobantes" ], "operationId": "enviar_retencion", "summary": "Enviar Comprobante de retención al SRI", "description": "Marca un borrador para que salga al SRI. AZUR genera el XML, lo firma y lo envía. **Solo funciona con documentos en estado borrador**: uno ya enviado devuelve `documento_no_editable`. Es irreversible: para deshacerlo hay que anular el comprobante.", "x-azur-visibilidad": "publico", "x-azur-tipo": "escritura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del documento." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Clave que usted inventa para esta operación. Si reintenta con la misma clave, se devuelve el resultado original en vez de crear un segundo documento. Se recuerda 24 horas. **Mándela siempre en lo que escriba**: si se corta la conexión, es lo único que evita el duplicado." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Documento" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/retencion/{id}/estado": { "get": { "tags": [ "Comprobantes" ], "operationId": "estado_retencion", "summary": "Estado de Comprobante de retención", "description": "En qué punto del camino está el documento, con el **código numérico** del estado -que es con lo que se ramifica un flujo y no cambia nunca-, lo que contestó el SRI si lo rechazó, y qué hacer.\n\nCon `sri=1` además se le pregunta al SRI en directo, que es la única forma de enterarse si alguien anuló el comprobante desde SRI en línea.", "x-azur-visibilidad": "publico", "x-azur-tipo": "lectura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del documento." }, { "name": "sri", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "A 1 para consultar también al SRI en directo (tarda unos segundos)." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Documento" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/retencion/{id}/anular": { "post": { "tags": [ "Comprobantes" ], "operationId": "anular_retencion", "summary": "Anular Comprobante de retención", "description": "**AZUR no anula en el SRI.** La solicitud de anulación la presenta el contribuyente en SRI en línea (Facturación Electrónica → Producción → Anulación). Lo que hace este endpoint es preguntarle al SRI si ese comprobante ya consta anulado y, si consta, darlo de baja también en AZUR: revierte el stock, el asiento contable y la cartera.\n\nSi la solicitud todavía no se ha presentado responde `anulacion_no_solicitada`; si pasó el plazo del SRI, `anulacion_fuera_de_plazo`. No anula una factura con pagos registrados, con notas de crédito vivas o con el asiento bloqueado: son las mismas guardas que el portal.", "x-azur-visibilidad": "publico", "x-azur-tipo": "escritura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del documento." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Clave que usted inventa para esta operación. Si reintenta con la misma clave, se devuelve el resultado original en vez de crear un segundo documento. Se recuerda 24 horas. **Mándela siempre en lo que escriba**: si se corta la conexión, es lo único que evita el duplicado." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Documento" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/retencion/{id}/reprocesar": { "post": { "tags": [ "Comprobantes" ], "operationId": "reprocesar_retencion", "summary": "Reprocesar Comprobante de retención", "description": "Vuelve a meter en la cola un documento que se quedó parado -no autorizado, error de secuencial, error al firmar, SRI no disponible-: se regenera el XML, se firma y se reenvía.\n\nNo sirve para un documento ya autorizado, ni para un borrador (ése se manda con `/enviar`), ni para «establecimiento cerrado», que es configuración del emisor en el SRI y no se arregla reintentando.", "x-azur-visibilidad": "publico", "x-azur-tipo": "escritura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del documento." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Clave que usted inventa para esta operación. Si reintenta con la misma clave, se devuelve el resultado original en vez de crear un segundo documento. Se recuerda 24 horas. **Mándela siempre en lo que escriba**: si se corta la conexión, es lo único que evita el duplicado." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Documento" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/retencion/{id}/correo": { "post": { "tags": [ "Comprobantes" ], "operationId": "correo_retencion", "summary": "Reenviar Comprobante de retención por correo", "description": "Reenvía el documento por correo con el PDF y el XML adjuntos, igual que el envío automático. Sin `correo` en el cuerpo va a los destinatarios que ya tiene el documento.", "x-azur-visibilidad": "publico", "x-azur-tipo": "escritura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del documento." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "correo": { "type": "string", "description": "A quién mandarlo. Si no se pone, a los correos del documento." } } } } } }, "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Documento" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/retencion/{id}/pdf": { "get": { "tags": [ "Comprobantes" ], "operationId": "pdf_retencion", "summary": "PDF de Comprobante de retención", "description": "Devuelve el PDF (RIDE) del documento. **Solo existe una vez enviado al SRI**: un borrador todavía no tiene clave de acceso. Si el fichero se perdió, se regenera. Con `base64=1` viaja dentro del JSON de siempre.", "x-azur-visibilidad": "publico", "x-azur-tipo": "lectura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del documento." }, { "name": "base64", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "A 1 para recibirlo dentro del JSON." } ], "responses": { "200": { "description": "El fichero. Con `base64=1`, el JSON de siempre.", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Archivo" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta, o el fichero todavía no existe.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta, o el fichero todavía no existe.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/retencion/{id}/xml": { "get": { "tags": [ "Comprobantes" ], "operationId": "xml_retencion", "summary": "XML de Comprobante de retención", "description": "Devuelve el XML **autorizado** por el SRI, que es el que tiene valor tributario y el único que se conserva. Con `tipo=firmado` devuelve el que se envió, extraído de dentro del autorizado. Solo existe si el SRI ya autorizó.", "x-azur-visibilidad": "publico", "x-azur-tipo": "lectura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del documento." }, { "name": "tipo", "in": "query", "required": false, "schema": { "type": "string" }, "description": "`autorizado` (por defecto) o `firmado`." }, { "name": "base64", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "A 1 para recibirlo dentro del JSON." } ], "responses": { "200": { "description": "El fichero. Con `base64=1`, el JSON de siempre.", "content": { "application/xml": { "schema": { "type": "string", "format": "binary" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Archivo" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta, o el fichero todavía no existe.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta, o el fichero todavía no existe.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/compra/guardar": { "post": { "tags": [ "Comprobantes" ], "operationId": "guardar_compra", "summary": "Guardar Compra", "description": "Crea un Compra en AZUR.\n\nCon `accion: \"guardar\"` queda como **borrador**: no sale a ninguna parte y se puede revisar antes.\n\nEste documento **no va al SRI**: es interno de AZUR.\n\nLos totales los calcula el servidor a partir de las líneas; no hace falta que los envíe.", "x-azur-visibilidad": "publico", "x-azur-tipo": "escritura", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Clave que usted inventa para esta operación. Si reintenta con la misma clave, se devuelve el resultado original en vez de crear un segundo documento. Se recuerda 24 horas. **Mándela siempre en lo que escriba**: si se corta la conexión, es lo único que evita el duplicado." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntradaCompra" } } } }, "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Documento" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/compra/{id}": { "get": { "tags": [ "Comprobantes" ], "operationId": "ver_compra", "summary": "Consultar Compra", "description": "Devuelve un Compra con sus líneas y formas de pago. Use el `id` que devolvió al guardarlo.", "x-azur-visibilidad": "publico", "x-azur-tipo": "lectura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del documento en AZUR." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Documento" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } }, "put": { "tags": [ "Comprobantes" ], "operationId": "editar_compra", "summary": "Editar Compra", "description": "Reemplaza el contenido de un borrador: cabecera, líneas y formas de pago. Lo que mande sustituye a lo que había, no se mezcla.\n\n**Solo sobre borradores.** Un documento que ya salió al SRI devuelve `documento_no_editable`; para corregir uno emitido hay que anularlo y hacer otro. El número asignado no cambia al editar.", "x-azur-visibilidad": "publico", "x-azur-tipo": "escritura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del borrador." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntradaCompra" } } } }, "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Documento" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } }, "delete": { "tags": [ "Comprobantes" ], "operationId": "eliminar_compra", "summary": "Eliminar Compra", "description": "Da de baja el documento. Se deshace lo que colgaba de él: líneas, cartera, asiento contable y movimiento de inventario.", "x-azur-visibilidad": "publico", "x-azur-tipo": "escritura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del documento." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Documento" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/compras": { "get": { "tags": [ "Comprobantes" ], "operationId": "listar_compra", "summary": "Listar Compra", "description": "Lista los documentos de este tipo, del más reciente al más antiguo. Filtre por fechas o busque por número.\n\n**Por defecto solo los últimos 60 días.** Si no manda `desde`, `hasta` ni `buscar`, la lista se limita a los últimos 60 días —lo mismo que hace el portal en esa pantalla—, y `total` cuenta solo eso. La respuesta lo dice en `datos.ventana` (`aplicada`, `dias`, `desde`) y con un aviso en `avisos`. En cuanto mande una fecha o una búsqueda no se le limita nada: `ventana.aplicada` viene en `false`.\n\n**Compra y liquidación de compra no se mezclan.** Se guardan en la misma tabla y se distinguen igual que en el portal: es liquidación la de tipo `03` emitida electrónicamente por usted, y es compra todo lo demás —incluida una liquidación en papel que le hayan dado, que es un documento recibido—. Este listado solo devuelve compras, y `GET /compra/{id}` solo abre compras: pedir por aquí un documento del otro tipo devuelve `no_encontrado`.\n\nCada fila trae `id`, `numero` —el completo, `EEE-PPP-SSSSSSSSS`—, `secuencial`, `fecha`, `total`, `estado` y **`cliente`**, con el nombre y la identificación de la contraparte. Aquí la contraparte es el **proveedor**, y así lo dice el campo `cliente.tipo`. El nombre sale de la ficha viva; si esa ficha ya no existe, queda al menos la identificación que se grabó en el documento.\n\nY trae `tiene_retencion` con su `id_retencion`: **a cuáles les falta emitir la retención**. Es el mismo campo que mira el portal para ofrecer o no el botón «Emitir Retención», y al anular una retención vuelve a quedar libre.", "x-azur-visibilidad": "publico", "x-azur-tipo": "lectura", "parameters": [ { "name": "desde", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Fecha de emisión desde (aaaa-mm-dd)." }, { "name": "hasta", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Fecha de emisión hasta (aaaa-mm-dd)." }, { "name": "buscar", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Parte del número del documento." }, { "name": "pagina", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Página, empezando en 1." }, { "name": "limite", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Cuántos por página, máximo 100." }, { "name": "modificado_desde", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Devuelve solo lo que CAMBIÓ desde ese momento (aaaa-mm-dd o aaaa-mm-dd hh:mm:ss), ordenado de más antiguo a más reciente. Es lo que hay que usar para sincronizar: a diferencia de «desde», que mira la fecha de emisión, esto sí devuelve una factura vieja que se acaba de anular o corregir." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Para seguir por donde se quedó. Se coge tal cual de «siguiente_cursor» de la llamada anterior; cuando venga vacío es que ya está al día. Con cursor NO se usa «pagina»: paginar por número se descoloca en cuanto entran documentos nuevos entre página y página." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Listado" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/liquidacion/guardar": { "post": { "tags": [ "Comprobantes" ], "operationId": "guardar_liquidacion", "summary": "Guardar Liquidación de compra", "description": "Crea un Liquidación de compra en AZUR.\n\nCon `accion: \"guardar\"` queda como **borrador**: no sale a ninguna parte y se puede revisar antes. Con `accion: \"enviar\"` se manda al SRI de inmediato.\n\nSi no está seguro de los datos, guarde primero como borrador y envíelo después: un comprobante que ya salió al SRI solo se puede corregir anulándolo.\n\nLos totales los calcula el servidor a partir de las líneas; no hace falta que los envíe.", "x-azur-visibilidad": "publico", "x-azur-tipo": "escritura", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Clave que usted inventa para esta operación. Si reintenta con la misma clave, se devuelve el resultado original en vez de crear un segundo documento. Se recuerda 24 horas. **Mándela siempre en lo que escriba**: si se corta la conexión, es lo único que evita el duplicado." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntradaCompra" } } } }, "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Documento" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/liquidacion/{id}": { "get": { "tags": [ "Comprobantes" ], "operationId": "ver_liquidacion", "summary": "Consultar Liquidación de compra", "description": "Devuelve un Liquidación de compra con sus líneas y formas de pago. Use el `id` que devolvió al guardarlo.", "x-azur-visibilidad": "publico", "x-azur-tipo": "lectura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del documento en AZUR." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Documento" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } }, "put": { "tags": [ "Comprobantes" ], "operationId": "editar_liquidacion", "summary": "Editar Liquidación de compra", "description": "Reemplaza el contenido de un borrador: cabecera, líneas y formas de pago. Lo que mande sustituye a lo que había, no se mezcla.\n\n**Solo sobre borradores.** Un documento que ya salió al SRI devuelve `documento_no_editable`; para corregir uno emitido hay que anularlo y hacer otro. El número asignado no cambia al editar.", "x-azur-visibilidad": "publico", "x-azur-tipo": "escritura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del borrador." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntradaCompra" } } } }, "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Documento" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } }, "delete": { "tags": [ "Comprobantes" ], "operationId": "eliminar_liquidacion", "summary": "Eliminar Liquidación de compra", "description": "Borra un documento que **nunca llegó a ser un comprobante**: el borrador que no se envió, o el que el SRI rechazó (no autorizado, error de secuencial, error al firmar). El secuencial queda libre.\n\nUn comprobante **autorizado no se borra: se anula** con `/anular`. Uno que está en la cola tampoco, porque el proceso lo tiene cogido.", "x-azur-visibilidad": "publico", "x-azur-tipo": "escritura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del documento." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Documento" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/liquidaciones": { "get": { "tags": [ "Comprobantes" ], "operationId": "listar_liquidacion", "summary": "Listar Liquidación de compra", "description": "Lista los documentos de este tipo, del más reciente al más antiguo. Filtre por fechas o busque por número.\n\n**Por defecto solo los últimos 60 días.** Si no manda `desde`, `hasta` ni `buscar`, la lista se limita a los últimos 60 días —lo mismo que hace el portal en esa pantalla—, y `total` cuenta solo eso. La respuesta lo dice en `datos.ventana` (`aplicada`, `dias`, `desde`) y con un aviso en `avisos`. En cuanto mande una fecha o una búsqueda no se le limita nada: `ventana.aplicada` viene en `false`.\n\n**Compra y liquidación de compra no se mezclan.** Se guardan en la misma tabla y se distinguen igual que en el portal: es liquidación la de tipo `03` emitida electrónicamente por usted, y es compra todo lo demás —incluida una liquidación en papel que le hayan dado, que es un documento recibido—. Este listado solo devuelve liquidaciones, y `GET /liquidacion/{id}` solo abre liquidaciones: pedir por aquí un documento del otro tipo devuelve `no_encontrado`.\n\nCada fila trae `id`, `numero` —el completo, `EEE-PPP-SSSSSSSSS`—, `secuencial`, `fecha`, `total`, `estado` y **`cliente`**, con el nombre y la identificación de la contraparte. Aquí la contraparte es el **proveedor**, y así lo dice el campo `cliente.tipo`. El nombre sale de la ficha viva; si esa ficha ya no existe, queda al menos la identificación que se grabó en el documento.\n\nY trae `tiene_retencion` con su `id_retencion`: **a cuáles les falta emitir la retención**. Es el mismo campo que mira el portal para ofrecer o no el botón «Emitir Retención», y al anular una retención vuelve a quedar libre.", "x-azur-visibilidad": "publico", "x-azur-tipo": "lectura", "parameters": [ { "name": "desde", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Fecha de emisión desde (aaaa-mm-dd)." }, { "name": "hasta", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Fecha de emisión hasta (aaaa-mm-dd)." }, { "name": "buscar", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Parte del número del documento." }, { "name": "pagina", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Página, empezando en 1." }, { "name": "limite", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Cuántos por página, máximo 100." }, { "name": "modificado_desde", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Devuelve solo lo que CAMBIÓ desde ese momento (aaaa-mm-dd o aaaa-mm-dd hh:mm:ss), ordenado de más antiguo a más reciente. Es lo que hay que usar para sincronizar: a diferencia de «desde», que mira la fecha de emisión, esto sí devuelve una factura vieja que se acaba de anular o corregir." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Para seguir por donde se quedó. Se coge tal cual de «siguiente_cursor» de la llamada anterior; cuando venga vacío es que ya está al día. Con cursor NO se usa «pagina»: paginar por número se descoloca en cuanto entran documentos nuevos entre página y página." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Listado" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/liquidacion/{id}/enviar": { "post": { "tags": [ "Comprobantes" ], "operationId": "enviar_liquidacion", "summary": "Enviar Liquidación de compra al SRI", "description": "Marca un borrador para que salga al SRI. AZUR genera el XML, lo firma y lo envía. **Solo funciona con documentos en estado borrador**: uno ya enviado devuelve `documento_no_editable`. Es irreversible: para deshacerlo hay que anular el comprobante.", "x-azur-visibilidad": "publico", "x-azur-tipo": "escritura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del documento." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Clave que usted inventa para esta operación. Si reintenta con la misma clave, se devuelve el resultado original en vez de crear un segundo documento. Se recuerda 24 horas. **Mándela siempre en lo que escriba**: si se corta la conexión, es lo único que evita el duplicado." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Documento" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/liquidacion/{id}/estado": { "get": { "tags": [ "Comprobantes" ], "operationId": "estado_liquidacion", "summary": "Estado de Liquidación de compra", "description": "En qué punto del camino está el documento, con el **código numérico** del estado -que es con lo que se ramifica un flujo y no cambia nunca-, lo que contestó el SRI si lo rechazó, y qué hacer.\n\nCon `sri=1` además se le pregunta al SRI en directo, que es la única forma de enterarse si alguien anuló el comprobante desde SRI en línea.", "x-azur-visibilidad": "publico", "x-azur-tipo": "lectura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del documento." }, { "name": "sri", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "A 1 para consultar también al SRI en directo (tarda unos segundos)." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Documento" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/liquidacion/{id}/anular": { "post": { "tags": [ "Comprobantes" ], "operationId": "anular_liquidacion", "summary": "Anular Liquidación de compra", "description": "**AZUR no anula en el SRI.** La solicitud de anulación la presenta el contribuyente en SRI en línea (Facturación Electrónica → Producción → Anulación). Lo que hace este endpoint es preguntarle al SRI si ese comprobante ya consta anulado y, si consta, darlo de baja también en AZUR: revierte el stock, el asiento contable y la cartera.\n\nSi la solicitud todavía no se ha presentado responde `anulacion_no_solicitada`; si pasó el plazo del SRI, `anulacion_fuera_de_plazo`. No anula una factura con pagos registrados, con notas de crédito vivas o con el asiento bloqueado: son las mismas guardas que el portal.", "x-azur-visibilidad": "publico", "x-azur-tipo": "escritura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del documento." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Clave que usted inventa para esta operación. Si reintenta con la misma clave, se devuelve el resultado original en vez de crear un segundo documento. Se recuerda 24 horas. **Mándela siempre en lo que escriba**: si se corta la conexión, es lo único que evita el duplicado." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Documento" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/liquidacion/{id}/reprocesar": { "post": { "tags": [ "Comprobantes" ], "operationId": "reprocesar_liquidacion", "summary": "Reprocesar Liquidación de compra", "description": "Vuelve a meter en la cola un documento que se quedó parado -no autorizado, error de secuencial, error al firmar, SRI no disponible-: se regenera el XML, se firma y se reenvía.\n\nNo sirve para un documento ya autorizado, ni para un borrador (ése se manda con `/enviar`), ni para «establecimiento cerrado», que es configuración del emisor en el SRI y no se arregla reintentando.", "x-azur-visibilidad": "publico", "x-azur-tipo": "escritura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del documento." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Clave que usted inventa para esta operación. Si reintenta con la misma clave, se devuelve el resultado original en vez de crear un segundo documento. Se recuerda 24 horas. **Mándela siempre en lo que escriba**: si se corta la conexión, es lo único que evita el duplicado." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Documento" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/liquidacion/{id}/correo": { "post": { "tags": [ "Comprobantes" ], "operationId": "correo_liquidacion", "summary": "Reenviar Liquidación de compra por correo", "description": "Reenvía el documento por correo con el PDF y el XML adjuntos, igual que el envío automático. Sin `correo` en el cuerpo va a los destinatarios que ya tiene el documento.", "x-azur-visibilidad": "publico", "x-azur-tipo": "escritura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del documento." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "correo": { "type": "string", "description": "A quién mandarlo. Si no se pone, a los correos del documento." } } } } } }, "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Documento" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/liquidacion/{id}/pdf": { "get": { "tags": [ "Comprobantes" ], "operationId": "pdf_liquidacion", "summary": "PDF de Liquidación de compra", "description": "Devuelve el PDF (RIDE) del documento. **Solo existe una vez enviado al SRI**: un borrador todavía no tiene clave de acceso. Si el fichero se perdió, se regenera. Con `base64=1` viaja dentro del JSON de siempre.", "x-azur-visibilidad": "publico", "x-azur-tipo": "lectura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del documento." }, { "name": "base64", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "A 1 para recibirlo dentro del JSON." } ], "responses": { "200": { "description": "El fichero. Con `base64=1`, el JSON de siempre.", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Archivo" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta, o el fichero todavía no existe.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta, o el fichero todavía no existe.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/liquidacion/{id}/xml": { "get": { "tags": [ "Comprobantes" ], "operationId": "xml_liquidacion", "summary": "XML de Liquidación de compra", "description": "Devuelve el XML **autorizado** por el SRI, que es el que tiene valor tributario y el único que se conserva. Con `tipo=firmado` devuelve el que se envió, extraído de dentro del autorizado. Solo existe si el SRI ya autorizó.", "x-azur-visibilidad": "publico", "x-azur-tipo": "lectura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del documento." }, { "name": "tipo", "in": "query", "required": false, "schema": { "type": "string" }, "description": "`autorizado` (por defecto) o `firmado`." }, { "name": "base64", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "A 1 para recibirlo dentro del JSON." } ], "responses": { "200": { "description": "El fichero. Con `base64=1`, el JSON de siempre.", "content": { "application/xml": { "schema": { "type": "string", "format": "binary" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Archivo" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta, o el fichero todavía no existe.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta, o el fichero todavía no existe.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/proforma/guardar": { "post": { "tags": [ "Comprobantes" ], "operationId": "guardar_proforma", "summary": "Guardar Proforma", "description": "Crea un Proforma en AZUR.\n\nCon `accion: \"guardar\"` queda como **borrador**: no sale a ninguna parte y se puede revisar antes.\n\nEste documento **no va al SRI**: es interno de AZUR.\n\nLos totales los calcula el servidor a partir de las líneas; no hace falta que los envíe.", "x-azur-visibilidad": "publico", "x-azur-tipo": "escritura", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Clave que usted inventa para esta operación. Si reintenta con la misma clave, se devuelve el resultado original en vez de crear un segundo documento. Se recuerda 24 horas. **Mándela siempre en lo que escriba**: si se corta la conexión, es lo único que evita el duplicado." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntradaDocumento" } } } }, "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Documento" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/proforma/{id}": { "get": { "tags": [ "Comprobantes" ], "operationId": "ver_proforma", "summary": "Consultar Proforma", "description": "Devuelve un Proforma con sus líneas y formas de pago. Use el `id` que devolvió al guardarlo.", "x-azur-visibilidad": "publico", "x-azur-tipo": "lectura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del documento en AZUR." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Documento" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } }, "put": { "tags": [ "Comprobantes" ], "operationId": "editar_proforma", "summary": "Editar Proforma", "description": "Reemplaza el contenido de un borrador: cabecera, líneas y formas de pago. Lo que mande sustituye a lo que había, no se mezcla.\n\n**Solo sobre borradores.** Un documento que ya salió al SRI devuelve `documento_no_editable`; para corregir uno emitido hay que anularlo y hacer otro. El número asignado no cambia al editar.", "x-azur-visibilidad": "publico", "x-azur-tipo": "escritura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del borrador." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntradaDocumento" } } } }, "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Documento" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } }, "delete": { "tags": [ "Comprobantes" ], "operationId": "eliminar_proforma", "summary": "Eliminar Proforma", "description": "Da de baja el documento. Se deshace lo que colgaba de él: líneas, cartera, asiento contable y movimiento de inventario.", "x-azur-visibilidad": "publico", "x-azur-tipo": "escritura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del documento." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Documento" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/proformas": { "get": { "tags": [ "Comprobantes" ], "operationId": "listar_proforma", "summary": "Listar Proforma", "description": "Lista los documentos de este tipo, del más reciente al más antiguo. Filtre por fechas o busque por número.\n\n**Por defecto solo los últimos 60 días.** Si no manda `desde`, `hasta` ni `buscar`, la lista se limita a los últimos 60 días —lo mismo que hace el portal en esa pantalla—, y `total` cuenta solo eso. La respuesta lo dice en `datos.ventana` (`aplicada`, `dias`, `desde`) y con un aviso en `avisos`. En cuanto mande una fecha o una búsqueda no se le limita nada: `ventana.aplicada` viene en `false`.\n\nCada fila trae `id`, `numero` —el completo, `EEE-PPP-SSSSSSSSS`—, `secuencial`, `fecha`, `total`, `estado` y **`cliente`**, con el nombre y la identificación de la contraparte. El nombre sale de la ficha viva; si esa ficha ya no existe, queda al menos la identificación que se grabó en el documento.", "x-azur-visibilidad": "publico", "x-azur-tipo": "lectura", "parameters": [ { "name": "desde", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Fecha de emisión desde (aaaa-mm-dd)." }, { "name": "hasta", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Fecha de emisión hasta (aaaa-mm-dd)." }, { "name": "buscar", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Parte del número del documento." }, { "name": "pagina", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Página, empezando en 1." }, { "name": "limite", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Cuántos por página, máximo 100." }, { "name": "modificado_desde", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Devuelve solo lo que CAMBIÓ desde ese momento (aaaa-mm-dd o aaaa-mm-dd hh:mm:ss), ordenado de más antiguo a más reciente. Es lo que hay que usar para sincronizar: a diferencia de «desde», que mira la fecha de emisión, esto sí devuelve una factura vieja que se acaba de anular o corregir." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Para seguir por donde se quedó. Se coge tal cual de «siguiente_cursor» de la llamada anterior; cuando venga vacío es que ya está al día. Con cursor NO se usa «pagina»: paginar por número se descoloca en cuanto entran documentos nuevos entre página y página." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Listado" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/proforma/{id}/correo": { "post": { "tags": [ "Comprobantes" ], "operationId": "correo_proforma", "summary": "Reenviar Proforma por correo", "description": "Reenvía el documento por correo con el PDF y el XML adjuntos, igual que el envío automático. Sin `correo` en el cuerpo va a los destinatarios que ya tiene el documento.", "x-azur-visibilidad": "publico", "x-azur-tipo": "escritura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del documento." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "correo": { "type": "string", "description": "A quién mandarlo. Si no se pone, a los correos del documento." } } } } } }, "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Documento" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/notaventa/guardar": { "post": { "tags": [ "Comprobantes" ], "operationId": "guardar_notaventa", "summary": "Guardar Nota de venta", "description": "Crea un Nota de venta en AZUR.\n\nCon `accion: \"guardar\"` queda como **borrador**: no sale a ninguna parte y se puede revisar antes.\n\nEste documento **no va al SRI**: es interno de AZUR.\n\nLos totales los calcula el servidor a partir de las líneas; no hace falta que los envíe.", "x-azur-visibilidad": "publico", "x-azur-tipo": "escritura", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Clave que usted inventa para esta operación. Si reintenta con la misma clave, se devuelve el resultado original en vez de crear un segundo documento. Se recuerda 24 horas. **Mándela siempre en lo que escriba**: si se corta la conexión, es lo único que evita el duplicado." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntradaDocumento" } } } }, "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Documento" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/notaventa/{id}": { "get": { "tags": [ "Comprobantes" ], "operationId": "ver_notaventa", "summary": "Consultar Nota de venta", "description": "Devuelve un Nota de venta con sus líneas y formas de pago. Use el `id` que devolvió al guardarlo.", "x-azur-visibilidad": "publico", "x-azur-tipo": "lectura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del documento en AZUR." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Documento" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } }, "put": { "tags": [ "Comprobantes" ], "operationId": "editar_notaventa", "summary": "Editar Nota de venta", "description": "Reemplaza el contenido de un borrador: cabecera, líneas y formas de pago. Lo que mande sustituye a lo que había, no se mezcla.\n\n**Solo sobre borradores.** Un documento que ya salió al SRI devuelve `documento_no_editable`; para corregir uno emitido hay que anularlo y hacer otro. El número asignado no cambia al editar.", "x-azur-visibilidad": "publico", "x-azur-tipo": "escritura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del borrador." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntradaDocumento" } } } }, "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Documento" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/notaventas": { "get": { "tags": [ "Comprobantes" ], "operationId": "listar_notaventa", "summary": "Listar Nota de venta", "description": "Lista los documentos de este tipo, del más reciente al más antiguo. Filtre por fechas o busque por número.\n\n**Por defecto solo los últimos 60 días.** Si no manda `desde`, `hasta` ni `buscar`, la lista se limita a los últimos 60 días —lo mismo que hace el portal en esa pantalla—, y `total` cuenta solo eso. La respuesta lo dice en `datos.ventana` (`aplicada`, `dias`, `desde`) y con un aviso en `avisos`. En cuanto mande una fecha o una búsqueda no se le limita nada: `ventana.aplicada` viene en `false`.\n\nCada fila trae `id`, `numero` —el completo, `EEE-PPP-SSSSSSSSS`—, `secuencial`, `fecha`, `total`, `estado` y **`cliente`**, con el nombre y la identificación de la contraparte. El nombre sale de la ficha viva; si esa ficha ya no existe, queda al menos la identificación que se grabó en el documento.", "x-azur-visibilidad": "publico", "x-azur-tipo": "lectura", "parameters": [ { "name": "desde", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Fecha de emisión desde (aaaa-mm-dd)." }, { "name": "hasta", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Fecha de emisión hasta (aaaa-mm-dd)." }, { "name": "buscar", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Parte del número del documento." }, { "name": "pagina", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Página, empezando en 1." }, { "name": "limite", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Cuántos por página, máximo 100." }, { "name": "modificado_desde", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Devuelve solo lo que CAMBIÓ desde ese momento (aaaa-mm-dd o aaaa-mm-dd hh:mm:ss), ordenado de más antiguo a más reciente. Es lo que hay que usar para sincronizar: a diferencia de «desde», que mira la fecha de emisión, esto sí devuelve una factura vieja que se acaba de anular o corregir." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Para seguir por donde se quedó. Se coge tal cual de «siguiente_cursor» de la llamada anterior; cuando venga vacío es que ya está al día. Con cursor NO se usa «pagina»: paginar por número se descoloca en cuanto entran documentos nuevos entre página y página." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Listado" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/compra/{id}/retencion-sugerida": { "get": { "tags": [ "Comprobantes" ], "operationId": "retencion_sugerida", "summary": "Retención que propone el sistema para una compra", "description": "**Las líneas de la retención, ya calculadas**, para una compra que ya está en AZUR. Sirve para no teclear nada: se pide, se revisa y se manda.\n\nEs lo mismo que hace la pantalla de compras del portal cuando se elige el proveedor: el **código de retención** y el **porcentaje** salen de lo que su ficha tenga configurado —«Retención fuente» y «Retención IVA»—, y las bases son las dos de la compra: el subtotal sin impuestos para renta y el IVA cargado para IVA. No se recalcula nada por cuenta propia: equivocarse en una base es retenerle de más o de menos a un proveedor.\n\n`propuesta` es el cuerpo **listo para mandar tal cual** a `POST /retencion/guardar`. Si el proveedor no tiene configurado qué se le retiene, `retenciones` viene vacío y se dice por qué en `avisos`.\n\n`emitible` dice si esa compra admite hoy una retención, y `motivos` qué falta cuando no: sin sustento tributario, sin número de documento, sin líneas, o porque **ya tiene una retención viva** —el portal tampoco deja emitir una segunda—.", "x-azur-visibilidad": "publico", "x-azur-tipo": "lectura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id de la compra. Sale de /compras." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetencionSugerida" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/comprobantes": { "get": { "tags": [ "Comprobantes" ], "operationId": "listar_comprobantes", "summary": "Listar todos los comprobantes", "description": "Todos los comprobantes electrónicos **juntos**, del más reciente al más antiguo, con el tipo indicado en cada fila. Es lo que enseña la pantalla «Documentos enviados» del portal, y sale de la misma consulta, así que la web y esta lista nunca se contradicen.\n\nÚselo cuando quiera «lo último que se emitió» sin saber de qué tipo es. Si ya sabe el tipo, `/facturas`, `/creditos`… siguen valiendo.\n\n**Solo comprobantes electrónicos.** La compra que no va al SRI, la proforma y la nota de venta no están aquí —tampoco en la pantalla del portal—: para esas siguen los listados `/compras`, `/proformas` y `/notaventas`.\n\nCada fila trae `id` (el del documento, el que se usa en `/{tipo}/{id}`), `recurso` (`factura`, `credito`…), `tipo` (el código del SRI: `01`, `04`…), `tipo_nombre`, `numero`, `secuencial`, `fecha`, `total`, `estado`, `es_borrador`, `claveacceso`, `ambiente`, `vendedor` y `cliente` —con el nombre y la identificación de la contraparte, que en retenciones y liquidaciones es el **proveedor**, como dice `cliente.tipo`—.\n\nVe exactamente lo mismo que el listado por tipo: la empresa, el establecimiento, el punto de emisión y el ambiente de la credencial.\n\n**Por defecto solo los últimos 60 días.** Si no manda `desde`, `hasta` ni `buscar`, la lista se limita a los últimos 60 días —lo mismo que hace el portal en esa pantalla—, y `total` cuenta solo eso. La respuesta lo dice en `datos.ventana` (`aplicada`, `dias`, `desde`) y con un aviso en `avisos`. En cuanto mande una fecha o una búsqueda no se le limita nada: `ventana.aplicada` viene en `false`.\n\n", "x-azur-visibilidad": "publico", "x-azur-tipo": "lectura", "parameters": [ { "name": "tipo", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Uno o varios tipos separados por coma. Vale el nombre —`factura`, `credito`, `debito`, `guia`, `retencion`, `liquidacion`— o el código del SRI —`01`, `04`, `05`, `06`, `07`, `03`—. Vacío = todos." }, { "name": "desde", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Fecha de emisión desde (aaaa-mm-dd)." }, { "name": "hasta", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Fecha de emisión hasta (aaaa-mm-dd)." }, { "name": "buscar", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Parte del número, del nombre o de la identificación de la persona." }, { "name": "estado", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Código de estado: `-1` borrador, `0` en proceso, `4`/`9` autorizado, `7` error al firmar. Vacío = todos." }, { "name": "global", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "A 1 para ver la empresa entera y no solo su establecimiento. Solo el dueño de la cuenta; a un vendedor se le ignora." }, { "name": "pagina", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Página, empezando en 1." }, { "name": "limite", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Cuántos por página, máximo 100." }, { "name": "modificado_desde", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Devuelve solo lo que CAMBIÓ desde ese momento (aaaa-mm-dd o aaaa-mm-dd hh:mm:ss), ordenado de más antiguo a más reciente. Es lo que hay que usar para sincronizar: a diferencia de «desde», que mira la fecha de emisión, esto sí devuelve una factura vieja que se acaba de anular o corregir." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Para seguir por donde se quedó. Se coge tal cual de «siguiente_cursor» de la llamada anterior; cuando venga vacío es que ya está al día. Con cursor NO se usa «pagina»: paginar por número se descoloca en cuanto entran documentos nuevos entre página y página." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Listado" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/clientes": { "get": { "tags": [ "Búsqueda" ], "operationId": "buscar_clientes", "summary": "Buscar clientes", "description": "Busca clientes por texto. Sirve el nombre, la identificación o el correo: por ejemplo «Ferretería El Tornillo».\n\n**Si hay más de un resultado, `unico` viene en `false` y hay que elegir.** No dé por buena la primera fila: dos registros parecidos pueden ser distintos, y equivocarse aquí significa emitir el documento a quien no era.", "x-azur-visibilidad": "publico", "x-azur-tipo": "lectura", "parameters": [ { "name": "buscar", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Texto a buscar. Vacío devuelve los primeros." }, { "name": "limite", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Cuántos devolver, máximo 100." }, { "name": "pagina", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Página, empezando en 1. La respuesta trae `paginas` y `hay_mas`." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Busqueda" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/proveedores": { "get": { "tags": [ "Búsqueda" ], "operationId": "buscar_proveedores", "summary": "Buscar proveedores", "description": "Busca proveedores por texto. Sirve el nombre, la identificación: por ejemplo «Distribuidora del Pacífico».\n\n**Si hay más de un resultado, `unico` viene en `false` y hay que elegir.** No dé por buena la primera fila: dos registros parecidos pueden ser distintos, y equivocarse aquí significa emitir el documento a quien no era.", "x-azur-visibilidad": "publico", "x-azur-tipo": "lectura", "parameters": [ { "name": "buscar", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Texto a buscar." }, { "name": "limite", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Cuántos devolver, máximo 100." }, { "name": "pagina", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Página, empezando en 1." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Busqueda" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/productos": { "get": { "tags": [ "Búsqueda" ], "operationId": "buscar_productos", "summary": "Buscar productos", "description": "Busca productos por texto. Sirve el nombre, la identificación, el código o la marca: por ejemplo «tornillos».\n\n**Si hay más de un resultado, `unico` viene en `false` y hay que elegir.** No dé por buena la primera fila: dos registros parecidos pueden ser distintos, y equivocarse aquí significa emitir el documento a quien no era.\n\nDevuelve el precio y las **existencias** de cada uno, para poder comprobar que hay antes de facturar.", "x-azur-visibilidad": "publico", "x-azur-tipo": "lectura", "parameters": [ { "name": "buscar", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Texto a buscar." }, { "name": "limite", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Cuántos devolver, máximo 100." }, { "name": "pagina", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Página, empezando en 1." }, { "name": "existencias", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Incluir existencias. Por defecto sí." }, { "name": "id_categoria", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Solo los de esa categoría. Los ids salen de /producto/categorias." }, { "name": "tipo", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Solo bienes (1) o solo servicios (2)." }, { "name": "id_bodega", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Existencias de ESA bodega en vez de las del establecimiento entero, que es lo que enseña la pantalla de facturar cuando se elige bodega. Los ids salen de /inventario/bodegas." }, { "name": "controla_inventario", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Solo los que LLEVAN inventario (1) o solo los que no (0). No es lo mismo que `tipo`: un BIEN con el control de existencias apagado tampoco tiene kardex, y ese no se quita filtrando por tipo. Sin el parametro vienen todos." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Busqueda" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/factura/saldo-acreditable": { "get": { "tags": [ "Comprobantes" ], "operationId": "saldo_acreditable_numero", "summary": "Saldo por acreditar, buscando por número", "description": "Cuánto queda por acreditar de una factura: su total, lo que ya le acreditaron notas de crédito anteriores, y la resta.\n\n**El tope de una nota de crédito no es el total de la factura, es este saldo.** Sin mirarlo se pueden emitir dos notas de crédito que sumadas pasan de lo que la factura vale, y el servidor las rechaza al guardar.\n\nCuentan las notas de crédito vivas (`estado = 1`) de la misma empresa y el mismo ambiente. Las anuladas no restan. Es el mismo cálculo que hace el portal, no una aproximación.\n\n`puede_acreditar` viene en `false` con el motivo escrito cuando la factura está anulada, fue emitida a consumidor final, o ya está acreditada del todo.\n\nSi el número no está en AZUR -una factura de papel o de otro sistema- **no es un error**: responde `200` con `en_azur` en `false` y `saldo` en `null`. Esa nota de crédito se emite con `factura_externa` en `true` y no hay tope que comprobar.", "x-azur-visibilidad": "publico", "x-azur-tipo": "lectura", "parameters": [ { "name": "numero", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Número de la factura: 001-001-000000123, o los 15 dígitos pegados." }, { "name": "excluir_id_nc", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Deja fuera del cálculo esa nota de crédito. Úselo al EDITAR una: si no, se compara contra sí misma y ninguna edición pasa." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaldoAcreditable" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/factura/{id}/saldo-acreditable": { "get": { "tags": [ "Comprobantes" ], "operationId": "saldo_acreditable", "summary": "Saldo por acreditar de una factura", "description": "Cuánto queda por acreditar de una factura: su total, lo que ya le acreditaron notas de crédito anteriores, y la resta.\n\n**El tope de una nota de crédito no es el total de la factura, es este saldo.** Sin mirarlo se pueden emitir dos notas de crédito que sumadas pasan de lo que la factura vale, y el servidor las rechaza al guardar.\n\nCuentan las notas de crédito vivas (`estado = 1`) de la misma empresa y el mismo ambiente. Las anuladas no restan. Es el mismo cálculo que hace el portal, no una aproximación.\n\n`puede_acreditar` viene en `false` con el motivo escrito cuando la factura está anulada, fue emitida a consumidor final, o ya está acreditada del todo.", "x-azur-visibilidad": "publico", "x-azur-tipo": "lectura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id de la factura. Sale de /facturas." }, { "name": "excluir_id_nc", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Deja fuera del cálculo esa nota de crédito. Úselo al EDITAR una." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaldoAcreditable" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/factura/{id}/lineas-acreditables": { "get": { "tags": [ "Comprobantes" ], "operationId": "lineas_acreditables", "summary": "Líneas de una factura que todavía se pueden acreditar", "description": "**Las líneas de la factura con lo que todavía se le puede acreditar en una nota de crédito**, en una sola llamada.\n\nEs el hermano de `/factura/{id}/saldo-acreditable`: aquel dice cuánto DINERO queda por acreditar, éste dice QUÉ LÍNEAS y CUÁNTAS UNIDADES de cada una. Sin él hay que pedir el detalle de cada nota de crédito previa para sumar lo ya acreditado por producto, y encima `GET /producto/{id}` por cada producto para saber si mueve inventario.\n\nEn cada línea, `cantidad` es la facturada, `acreditada` lo que ya devolvieron las notas de crédito **vivas** de esa factura —las anuladas no cuentan—, y `disponible` la resta: **ése es el tope de esa línea**. Cuando llega a cero, `agotada` viene en `true`.\n\n`preciounitario` es **el de la factura**, no el que tenga hoy la ficha del producto: se acredita lo que se cobró.\n\n`descuento` es el de la línea original y **solo se copia si se acredita la cantidad entera**; no se prorratea. Es la regla del portal: si acredita una parte, mande la línea sin descuento.\n\n`manejastock` dice si ese producto lleva inventario (es un BIEN con control de existencias). Si es `false`, devolverlo al inventario no significa nada y `reversar_producto` sobra en esa línea.\n\n`acreditable` y `motivos` dicen si la factura admite hoy una nota de crédito: anulada, a consumidor final, ya acreditada del todo o con todas las líneas agotadas. **Las líneas se devuelven igual** aunque no sea acreditable: el motivo puede desaparecer si se anula una nota previa. Queda una cuarta regla que aquí no se puede comprobar —que el comprador de la nota sea el mismo de la factura—: compárelo contra `identificacion`.\n\n**Ojo**: lo ya acreditado se cuenta **por producto**, no por línea —es como lo calcula el portal—. Si el mismo producto aparece en varias líneas de la factura, ese total se le resta a cada una y el `disponible` de cada línea sale corto; el tope real de ese producto es su cantidad sumada menos lo acreditado. Cuando pasa, se dice en `avisos`.\n\nLa factura que **no está en AZUR** no tiene líneas que traer: esa nota de crédito se emite con `factura_externa` en `true` y las líneas se escriben a mano.", "x-azur-visibilidad": "publico", "x-azur-tipo": "lectura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id de la factura. Sale de /facturas." }, { "name": "excluir_id_nc", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Deja fuera del cálculo esa nota de crédito. Úselo al EDITAR una: si no, se compara contra sí misma y sus propias líneas salen como ya acreditadas." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LineasAcreditables" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/transportistas": { "get": { "tags": [ "Búsqueda" ], "operationId": "buscar_transportistas", "summary": "Buscar transportistas", "description": "Por nombre, identificación o **placa**. Devuelve el `id`, que es lo que hace falta para emitir una guía de remisión: hasta ahora los transportistas se podían crear pero no listar, así que no había de dónde sacarlo.", "x-azur-visibilidad": "publico", "x-azur-tipo": "lectura", "parameters": [ { "name": "buscar", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Nombre, identificación o placa." }, { "name": "pagina", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Página, empezando en 1." }, { "name": "limite", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Cuántos por página." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Listado" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/producto/categorias": { "get": { "tags": [ "Búsqueda" ], "operationId": "categorias_producto", "summary": "Categorías de productos", "description": "Las categorías de productos del establecimiento de la credencial, con cuántos productos activos tiene cada una.\n\nSirven para filtrar `/productos` con `id_categoria`, que es como se factura en un mostrador: primero la categoría y después el producto.\n\n`id_categoriapadre` viene en `null` cuando la categoría cuelga de la raíz; con él se arma el árbol completo.", "x-azur-visibilidad": "publico", "x-azur-tipo": "lectura", "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Categorias" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/catalogos/sri": { "get": { "tags": [ "Búsqueda" ], "operationId": "catalogos_sri", "summary": "Catálogos del SRI: unidades, ICE e IRBPNR", "description": "Los tres catálogos que hacen falta para dar de alta un producto, en una sola llamada: `unidades`, `ice` e `irbpnr`.\n\nSon de AZUR entero, no de la cuenta: los mismos para todos.\n\n**Ojo con la diferencia**: en el producto, `codigo_ice` guarda el **código** del ICE, pero `codigo_irbpnr` guarda el **id** de la fila de IRBPNR. Por eso el IRBPNR devuelve las dos cosas.", "x-azur-visibilidad": "publico", "x-azur-tipo": "lectura", "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogosSri" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/catalogos/unidades": { "get": { "tags": [ "Búsqueda" ], "operationId": "catalogo_unidades", "summary": "Unidades de medida", "description": "El catálogo de unidades de medida, para el campo `unidad` de un producto.\n\n`999` es «Sin Especificar», que es lo que lleva un producto al que no se le puso unidad.", "x-azur-visibilidad": "publico", "x-azur-tipo": "lectura", "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogosSri" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/catalogos/ice": { "get": { "tags": [ "Búsqueda" ], "operationId": "catalogo_ice", "summary": "Códigos de ICE", "description": "Los códigos de Impuesto a los Consumos Especiales con su texto. El `codigo` es lo que va en `codigo_ice` del producto.", "x-azur-visibilidad": "publico", "x-azur-tipo": "lectura", "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogosSri" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/catalogos/irbpnr": { "get": { "tags": [ "Búsqueda" ], "operationId": "catalogo_irbpnr", "summary": "Códigos de IRBPNR", "description": "Impuesto Redimible a las Botellas Plásticas no Retornables.\n\nEn el producto, `codigo_irbpnr` guarda el **`id`** de la fila, no su `codigo`; es al revés que en el ICE, y por eso vienen los dos.", "x-azur-visibilidad": "publico", "x-azur-tipo": "lectura", "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogosSri" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/producto/{id}/stock": { "get": { "tags": [ "Búsqueda" ], "operationId": "stock_producto", "summary": "Existencias de un producto", "description": "Cuántas unidades hay de un producto.\n\nSin `id_bodega` se suma **todo el establecimiento**; con ella se responde por esa bodega.\n\n`stock_real` es aparte y es el que sirve para decidir una línea: es siempre el de UNA bodega -la pedida, la del producto, o la que el establecimiento tenga por defecto- y viene con `id_bodega_stock` diciendo cuál. Es el mismo número que enseña la pantalla de facturar.\n\nSi el producto no lleva inventario, `controla_inventario` viene en `false` y no hay existencias que dar: es lo normal en servicios.", "x-azur-visibilidad": "publico", "x-azur-tipo": "lectura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del producto." }, { "name": "id_bodega", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Existencias de ESA bodega en vez de las del establecimiento entero. Los ids salen de /inventario/bodegas." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Stock" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/producto/{id}/lotes": { "get": { "tags": [ "Búsqueda" ], "operationId": "lotes_producto", "summary": "Lotes disponibles de un producto", "description": "**Los lotes entre los que elegir al vender**, con lo que hay de cada uno, su caducidad, su fecha de ingreso, y cuál propone el sistema.\n\nEs lo mismo que resuelve la pantalla de facturar del portal, con las mismas funciones: el orden sale de la configuración del producto y de la empresa, los saldos del libro de movimientos y la propuesta del mismo repartidor que usará el motor al guardar. Lo que aquí se ve y lo que allí se graba no pueden discrepar.\n\n`orden_despacho` dice cómo se despacha: `fefo` (caduca antes, sale antes), `fifo` (entró antes, sale antes) o `manual` (elige la persona; en ese caso **no hay sugerencia**, y si nadie elige, la venta se graba sin lote).\n\n`trazabilidad` es `0` (no lleva), `1` (lote) o `2` (serie / IMEI). `controla_caducidad` dice si hay que enseñar la fecha.\n\nCon `cantidad` se devuelve además `sugerencia`: el reparto propuesto, que se puede mandar **tal cual** en el campo `lote` de la línea al guardar el comprobante. `faltante` es lo que no alcanzan los lotes.\n\nSi la empresa no lleva lotes, o el producto no lleva trazabilidad, **no es un error**: responde `200` con la lista vacía y `lleva_lote` en `false`, y a esa línea no hay que preguntarle nada.", "x-azur-visibilidad": "publico", "x-azur-tipo": "lectura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del producto." }, { "name": "id_bodega", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Solo los lotes con saldo en ESA bodega. Sin ella, los del establecimiento." }, { "name": "cantidad", "in": "query", "required": false, "schema": { "type": "number" }, "description": "Cuántas unidades se van a despachar. Solo con ella se calcula `sugerencia`." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LotesProducto" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/contexto": { "get": { "tags": [ "Cuenta" ], "operationId": "contexto", "summary": "Sobre qué se está trabajando", "description": "Devuelve la empresa, el establecimiento, el punto de emisión y el **ambiente** de la credencial, más su régimen tributario y sus decimales.\n\nLlámelo al empezar: los decimales del establecimiento deciden cómo se redondea, y el ambiente dice si lo que emita es real.", "x-azur-visibilidad": "publico", "x-azur-tipo": "lectura", "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contexto" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/plan": { "get": { "tags": [ "Cuenta" ], "operationId": "plan", "summary": "Plan y comprobantes disponibles", "description": "Cuántos comprobantes quedan.\n\nMírelo antes de una carga grande: si se acaban, deja de poder emitirse y las llamadas empiezan a devolver `cupo_agotado`.", "x-azur-visibilidad": "publico", "x-azur-tipo": "lectura", "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Plan" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/firma": { "get": { "tags": [ "Cuenta" ], "operationId": "firma", "summary": "Vigencia de la firma electrónica", "description": "Hasta cuándo vale el certificado de firma, cuántos días le quedan y quién lo emitió.\n\n**Míre­lo periódicamente.** Cuando la firma caduca deja de salir todo: los comprobantes se quedan en «error al firmar» y quien emite por API suele enterarse con veinte facturas ya paradas. Con esto se avisa solo, con semanas de antelación.\n\nNo devuelve ni la contraseña ni el fichero de la firma.", "x-azur-visibilidad": "publico", "x-azur-tipo": "lectura", "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contexto" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/vendedores": { "get": { "tags": [ "Cuenta" ], "operationId": "vendedores", "summary": "Vendedores de la cuenta", "description": "Quiénes venden, con su `id` —que es el que se manda como `id_vendedor` al emitir—, su nivel de acceso y su punto de emisión.\n\nSin esto, una integración no tenía de dónde sacar el id y toda su facturación quedaba sin vendedor. No devuelve usuarios ni contraseñas.", "x-azur-visibilidad": "publico", "x-azur-tipo": "lectura", "parameters": [ { "name": "buscar", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Nombre o identificación." }, { "name": "global", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "A 1 los de toda la empresa, no solo los de este establecimiento." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Listado" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/secuenciales": { "get": { "tags": [ "Cuenta" ], "operationId": "secuenciales", "summary": "Por qué número va cada serie", "description": "El número que le toca al siguiente comprobante de cada tipo en **este** punto de emisión, ya con sus nueve dígitos y con el número completo `EEE-PPP-SSSSSSSSS`.\n\nHace falta para emitir mandando el secuencial a mano: sin esto, después de cualquier interrupción hay que adivinar y se cae en `secuencial_ocupado`.\n\nCada punto guarda dos series por tipo, una por ambiente; se devuelve la del ambiente de la credencial. Y es una foto: si alguien emite antes que usted, cambia.", "x-azur-visibilidad": "publico", "x-azur-tipo": "lectura", "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contexto" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/establecimientos": { "get": { "tags": [ "Cuenta" ], "operationId": "establecimientos", "summary": "Establecimientos de la empresa", "description": "Los establecimientos de la empresa. El marcado con `actual` es sobre el que trabaja esta credencial; para operar sobre otro hace falta la credencial de ese otro.", "x-azur-visibilidad": "publico", "x-azur-tipo": "lectura", "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Listado" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/puntos-emision": { "get": { "tags": [ "Cuenta" ], "operationId": "puntos_emision", "summary": "Puntos de emisión del establecimiento", "description": "Los puntos de emisión del establecimiento actual.", "x-azur-visibilidad": "publico", "x-azur-tipo": "lectura", "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Listado" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/resumen/ventas": { "get": { "tags": [ "Cuenta" ], "operationId": "resumen_ventas", "summary": "Resumen de ventas", "description": "Cuánto se ha facturado en un período, con el desglose por día y la comparación con el período anterior. Por defecto, el mes en curso.", "x-azur-visibilidad": "publico", "x-azur-tipo": "lectura", "parameters": [ { "name": "desde", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Desde (aaaa-mm-dd). Por defecto, el día 1 del mes." }, { "name": "hasta", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Hasta (aaaa-mm-dd). Por defecto, fin de mes." }, { "name": "por_dia_desde", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Alarga SOLO el desglose diario hacia atras (aaaa-mm-dd), sin mover `facturado`, `documentos` ni `comparacion`. Sirve para pintar «esta semana» cuando el lunes cae en el mes anterior. Solo hacia atras y con tope de 62 dias; la respuesta declara en `por_dia_desde` la cobertura que de verdad tiene." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Resumen" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/cliente": { "post": { "tags": [ "Catálogos" ], "operationId": "crear_cliente", "summary": "Crear cliente", "description": "Da de alta un cliente nuevo.\n\nEl cliente es a quien se le factura: su identificación y su nombre salen impresos en el comprobante y viajan al SRI. Una cédula mal escrita hace que el SRI devuelva el documento.\n\nSu dirección, teléfono y correo se guardan en su **sucursal**, no en su ficha — por eso el alta pide dirección. Al crearlo se le hace una, «MATRIZ»/«001»; si tiene más locales, se añaden por `POST /cliente/{id}/sucursal` y se elige a cuál se factura con `cliente.id_sucursal`.\n\n**Si ya existe uno con esa identificación, se devuelve ese** y no se crea otro: viene `ya_existia: true` y un aviso. Sus datos **no se tocan** — para cambiarlos, use el PUT sobre el id que devuelve.", "x-azur-visibilidad": "publico", "x-azur-tipo": "escritura", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Clave que usted inventa para esta operación. Si reintenta con la misma clave, se devuelve el resultado original en vez de crear un segundo documento. Se recuerda 24 horas. **Mándela siempre en lo que escriba**: si se corta la conexión, es lo único que evita el duplicado." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntradaCliente" } } } }, "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Registro" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/cliente/{id}": { "get": { "tags": [ "Catálogos" ], "operationId": "ver_cliente", "summary": "Consultar cliente", "description": "Devuelve la ficha completa de un cliente.", "x-azur-visibilidad": "publico", "x-azur-tipo": "lectura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del cliente." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Registro" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } }, "put": { "tags": [ "Catálogos" ], "operationId": "editar_cliente", "summary": "Editar cliente", "description": "Cambia los datos de un cliente. Solo se toca lo que mande; lo que omita se queda como estaba.\n\nLos documentos ya emitidos **no cambian**: guardan copia de los datos que tenían al emitirse, que es lo que fue al SRI.", "x-azur-visibilidad": "publico", "x-azur-tipo": "escritura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del cliente." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntradaCliente" } } } }, "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Registro" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } }, "delete": { "tags": [ "Catálogos" ], "operationId": "eliminar_cliente", "summary": "Dar de baja un cliente", "description": "Lo saca de las búsquedas y de las pantallas.\n\n**No borra nada.** El registro se marca como inactivo y sigue ahí, porque los documentos que ya lo usaron tienen que poder seguir consultándose. Volver a darlo de alta con la misma identificación recupera el mismo registro.", "x-azur-visibilidad": "publico", "x-azur-tipo": "escritura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del cliente." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Registro" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/cliente/{id}/activar": { "post": { "tags": [ "Catálogos" ], "operationId": "activar_cliente", "summary": "Reactivar un cliente", "description": "Deshace la baja: vuelve a dejar el cliente activo y visible en las búsquedas.\n\nEs la vuelta atrás del `DELETE`, que no borra sino que desactiva. Sin esto, algo dado de baja por error solo se rescataba entrando al portal.", "x-azur-visibilidad": "publico", "x-azur-tipo": "escritura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del cliente." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Registro" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/proveedor": { "post": { "tags": [ "Catálogos" ], "operationId": "crear_proveedor", "summary": "Crear proveedor", "description": "Da de alta un proveedor nuevo.\n\nEl proveedor es a quien se le compra. Se usa en compras, liquidaciones y retenciones.\n\nSu dirección, teléfono y correo se guardan en su **sucursal**, no en su ficha. Al crearlo se le hace una, «MATRIZ»/«001»; las demás, por `POST /proveedor/{id}/sucursal`.\n\n**Si ya existe uno con esa identificación, se devuelve ese** y no se crea otro: viene `ya_existia: true` y un aviso. Sus datos **no se tocan** — para cambiarlos, use el PUT sobre el id que devuelve.", "x-azur-visibilidad": "publico", "x-azur-tipo": "escritura", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Clave que usted inventa para esta operación. Si reintenta con la misma clave, se devuelve el resultado original en vez de crear un segundo documento. Se recuerda 24 horas. **Mándela siempre en lo que escriba**: si se corta la conexión, es lo único que evita el duplicado." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntradaProveedor" } } } }, "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Registro" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/proveedor/{id}": { "get": { "tags": [ "Catálogos" ], "operationId": "ver_proveedor", "summary": "Consultar proveedor", "description": "Devuelve la ficha completa de un proveedor.", "x-azur-visibilidad": "publico", "x-azur-tipo": "lectura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del proveedor." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Registro" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } }, "put": { "tags": [ "Catálogos" ], "operationId": "editar_proveedor", "summary": "Editar proveedor", "description": "Cambia los datos de un proveedor. Solo se toca lo que mande; lo que omita se queda como estaba.\n\nLos documentos ya emitidos **no cambian**: guardan copia de los datos que tenían al emitirse, que es lo que fue al SRI.", "x-azur-visibilidad": "publico", "x-azur-tipo": "escritura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del proveedor." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntradaProveedor" } } } }, "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Registro" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } }, "delete": { "tags": [ "Catálogos" ], "operationId": "eliminar_proveedor", "summary": "Dar de baja un proveedor", "description": "Lo saca de las búsquedas y de las pantallas.\n\n**No borra nada.** El registro se marca como inactivo y sigue ahí, porque los documentos que ya lo usaron tienen que poder seguir consultándose. Volver a darlo de alta con la misma identificación recupera el mismo registro.", "x-azur-visibilidad": "publico", "x-azur-tipo": "escritura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del proveedor." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Registro" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/proveedor/{id}/activar": { "post": { "tags": [ "Catálogos" ], "operationId": "activar_proveedor", "summary": "Reactivar un proveedor", "description": "Deshace la baja: vuelve a dejar el proveedor activo y visible en las búsquedas.\n\nEs la vuelta atrás del `DELETE`, que no borra sino que desactiva. Sin esto, algo dado de baja por error solo se rescataba entrando al portal.", "x-azur-visibilidad": "publico", "x-azur-tipo": "escritura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del proveedor." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Registro" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/transportista": { "post": { "tags": [ "Catálogos" ], "operationId": "crear_transportista", "summary": "Crear transportista", "description": "Da de alta un transportista nuevo.\n\nEl transportista es quien traslada la mercadería en una guía de remisión. Necesita placa y licencia.\n\n**Si ya existe uno con esa identificación, se devuelve ese** y no se crea otro: viene `ya_existia: true` y un aviso. Sus datos **no se tocan** — para cambiarlos, use el PUT sobre el id que devuelve.", "x-azur-visibilidad": "publico", "x-azur-tipo": "escritura", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Clave que usted inventa para esta operación. Si reintenta con la misma clave, se devuelve el resultado original en vez de crear un segundo documento. Se recuerda 24 horas. **Mándela siempre en lo que escriba**: si se corta la conexión, es lo único que evita el duplicado." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntradaTransportista" } } } }, "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Registro" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/transportista/{id}": { "get": { "tags": [ "Catálogos" ], "operationId": "ver_transportista", "summary": "Consultar transportista", "description": "Devuelve la ficha completa de un transportista.", "x-azur-visibilidad": "publico", "x-azur-tipo": "lectura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del transportista." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Registro" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } }, "put": { "tags": [ "Catálogos" ], "operationId": "editar_transportista", "summary": "Editar transportista", "description": "Cambia los datos de un transportista. Solo se toca lo que mande; lo que omita se queda como estaba.\n\nLos documentos ya emitidos **no cambian**: guardan copia de los datos que tenían al emitirse, que es lo que fue al SRI.", "x-azur-visibilidad": "publico", "x-azur-tipo": "escritura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del transportista." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntradaTransportista" } } } }, "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Registro" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } }, "delete": { "tags": [ "Catálogos" ], "operationId": "eliminar_transportista", "summary": "Dar de baja un transportista", "description": "Lo saca de las búsquedas y de las pantallas.\n\n**No borra nada.** El registro se marca como inactivo y sigue ahí, porque los documentos que ya lo usaron tienen que poder seguir consultándose. Volver a darlo de alta con la misma identificación recupera el mismo registro.", "x-azur-visibilidad": "publico", "x-azur-tipo": "escritura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del transportista." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Registro" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/transportista/{id}/activar": { "post": { "tags": [ "Catálogos" ], "operationId": "activar_transportista", "summary": "Reactivar un transportista", "description": "Deshace la baja: vuelve a dejar el transportista activo y visible en las búsquedas.\n\nEs la vuelta atrás del `DELETE`, que no borra sino que desactiva. Sin esto, algo dado de baja por error solo se rescataba entrando al portal.", "x-azur-visibilidad": "publico", "x-azur-tipo": "escritura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del transportista." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Registro" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/producto": { "post": { "tags": [ "Catálogos" ], "operationId": "crear_producto", "summary": "Crear producto", "description": "Da de alta un producto nuevo.\n\nSi el producto controla inventario, al crearlo **no se le pone existencia**: la existencia entra por un movimiento de inventario, que es lo que deja rastro en el kardex.\n\n**Si ya existe uno con esa identificación, se devuelve ese** y no se crea otro: viene `ya_existia: true` y un aviso. Sus datos **no se tocan** — para cambiarlos, use el PUT sobre el id que devuelve.", "x-azur-visibilidad": "publico", "x-azur-tipo": "escritura", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Clave que usted inventa para esta operación. Si reintenta con la misma clave, se devuelve el resultado original en vez de crear un segundo documento. Se recuerda 24 horas. **Mándela siempre en lo que escriba**: si se corta la conexión, es lo único que evita el duplicado." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntradaProducto" } } } }, "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Registro" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/producto/{id}": { "get": { "tags": [ "Catálogos" ], "operationId": "ver_producto", "summary": "Consultar producto", "description": "Devuelve la ficha completa de un producto.", "x-azur-visibilidad": "publico", "x-azur-tipo": "lectura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del producto." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Registro" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } }, "put": { "tags": [ "Catálogos" ], "operationId": "editar_producto", "summary": "Editar producto", "description": "Cambia los datos de un producto. Solo se toca lo que mande; lo que omita se queda como estaba.\n\nLos documentos ya emitidos **no cambian**: guardan copia de los datos que tenían al emitirse, que es lo que fue al SRI.", "x-azur-visibilidad": "publico", "x-azur-tipo": "escritura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del producto." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntradaProducto" } } } }, "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Registro" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } }, "delete": { "tags": [ "Catálogos" ], "operationId": "eliminar_producto", "summary": "Dar de baja un producto", "description": "Lo saca de las búsquedas y de las pantallas.\n\n**No borra nada.** El registro se marca como inactivo y sigue ahí, porque los documentos que ya lo usaron tienen que poder seguir consultándose. Volver a darlo de alta con la misma identificación recupera el mismo registro.", "x-azur-visibilidad": "publico", "x-azur-tipo": "escritura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del producto." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Registro" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/producto/{id}/activar": { "post": { "tags": [ "Catálogos" ], "operationId": "activar_producto", "summary": "Reactivar un producto", "description": "Deshace la baja: vuelve a dejar el producto activo y visible en las búsquedas.\n\nEs la vuelta atrás del `DELETE`, que no borra sino que desactiva. Sin esto, algo dado de baja por error solo se rescataba entrando al portal.", "x-azur-visibilidad": "publico", "x-azur-tipo": "escritura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del producto." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Registro" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/cliente/{id}/sucursales": { "get": { "tags": [ "Catálogos" ], "operationId": "sucursales_cliente", "summary": "Sucursales de un cliente", "description": "Los locales de un cliente, con cuál está marcado por defecto.\n\n**La dirección, el teléfono y el correo de un cliente no están en su ficha: están en su sucursal.** Es lo que más despista de este modelo, y explica por qué dar de alta un cliente pide dirección — lo que hace por debajo es crearle su primera sucursal, «MATRIZ»/«001».\n\nY no es solo del CRM: al emitir, la `direccionComprador` que va al SRI y el correo al que se manda el comprobante salen de la sucursal elegida. Por eso los documentos aceptan `id_sucursal`.\n\nVienen primero la marcada por defecto y luego el resto por antigüedad, que es el mismo orden en el que el portal las presenta. Con `incluir_inactivas=1` salen también las dadas de baja.", "x-azur-visibilidad": "publico", "x-azur-tipo": "lectura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del cliente." }, { "name": "incluir_inactivas", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Incluir también las que están dadas de baja." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Listado" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/cliente/{id}/sucursal": { "post": { "tags": [ "Catálogos" ], "operationId": "crear_sucursal_cliente", "summary": "Crear una sucursal de un cliente", "description": "Añade otro local a un cliente que ya existe. Hasta ahora esto solo se podía hacer desde el portal, en Menú → Clientes → Editar Sucursales.\n\n**La dirección, el teléfono y el correo de un cliente no están en su ficha: están en su sucursal.** Es lo que más despista de este modelo, y explica por qué dar de alta un cliente pide dirección — lo que hace por debajo es crearle su primera sucursal, «MATRIZ»/«001».\n\nY no es solo del CRM: al emitir, la `direccionComprador` que va al SRI y el correo al que se manda el comprobante salen de la sucursal elegida. Por eso los documentos aceptan `id_sucursal`.\n\nNace **activa** y **no** por defecto, igual que en la pantalla — salvo que sea la primera sucursal activa de ese cliente, y entonces queda por defecto para que la emisión no tenga que adivinar. Con `por_defecto` en `true` se marca directamente, y la que lo estuviera se desmarca sola.", "x-azur-visibilidad": "publico", "x-azur-tipo": "escritura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del cliente." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Clave que usted inventa para esta operación. Si reintenta con la misma clave, se devuelve el resultado original en vez de crear un segundo documento. Se recuerda 24 horas. **Mándela siempre en lo que escriba**: si se corta la conexión, es lo único que evita el duplicado." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntradaSucursal" } } } }, "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Registro" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/cliente/{id}/sucursal/{sucursal}": { "put": { "tags": [ "Catálogos" ], "operationId": "editar_sucursal_cliente", "summary": "Editar una sucursal de un cliente", "description": "Cambia los datos de un local, lo marca por defecto, o lo da de baja y lo recupera. Solo se toca lo que mande.\n\n**Los comprobantes ya emitidos apuntan a esta sucursal por su id, no guardan copia de la dirección**: cambiarla aquí cambia lo que se ve al reimprimir esos documentos. Lo que ya se firmó y se envió al SRI no cambia — eso queda congelado en el XML autorizado.", "x-azur-visibilidad": "publico", "x-azur-tipo": "escritura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del cliente." }, { "name": "sucursal", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id de la sucursal." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntradaSucursal" } } } }, "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Registro" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } }, "delete": { "tags": [ "Catálogos" ], "operationId": "eliminar_sucursal_cliente", "summary": "Dar de baja una sucursal", "description": "La saca de las listas y ya no se puede facturar a ella.\n\n**No borra nada**: se marca como inactiva, porque los comprobantes que ya la usaron la vuelven a leer para reimprimirse. Se puede recuperar con `activa: true` en el PUT.\n\n**La sucursal por defecto no se puede dar de baja**: marque otra primero. Si tiene comprobantes emitidos sí se puede — el portal también lo permite — y la respuesta lo avisa diciendo cuántos son.", "x-azur-visibilidad": "publico", "x-azur-tipo": "escritura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del cliente." }, { "name": "sucursal", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id de la sucursal." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Registro" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/proveedor/{id}/sucursales": { "get": { "tags": [ "Catálogos" ], "operationId": "sucursales_proveedor", "summary": "Sucursales de un proveedor", "description": "Los locales de un proveedor, con cuál está marcado por defecto.\n\n**La dirección, el teléfono y el correo de un cliente no están en su ficha: están en su sucursal.** Es lo que más despista de este modelo, y explica por qué dar de alta un cliente pide dirección — lo que hace por debajo es crearle su primera sucursal, «MATRIZ»/«001».\n\nY no es solo del CRM: al emitir, la `direccionComprador` que va al SRI y el correo al que se manda el comprobante salen de la sucursal elegida. Por eso los documentos aceptan `id_sucursal`.\n\nVienen primero la marcada por defecto y luego el resto por antigüedad, que es el mismo orden en el que el portal las presenta. Con `incluir_inactivas=1` salen también las dadas de baja.", "x-azur-visibilidad": "publico", "x-azur-tipo": "lectura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del proveedor." }, { "name": "incluir_inactivas", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Incluir también las que están dadas de baja." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Listado" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/proveedor/{id}/sucursal": { "post": { "tags": [ "Catálogos" ], "operationId": "crear_sucursal_proveedor", "summary": "Crear una sucursal de un proveedor", "description": "Añade otro local a un proveedor que ya existe. Hasta ahora esto solo se podía hacer desde el portal, en Menú → Clientes → Editar Sucursales.\n\n**La dirección, el teléfono y el correo de un cliente no están en su ficha: están en su sucursal.** Es lo que más despista de este modelo, y explica por qué dar de alta un cliente pide dirección — lo que hace por debajo es crearle su primera sucursal, «MATRIZ»/«001».\n\nY no es solo del CRM: al emitir, la `direccionComprador` que va al SRI y el correo al que se manda el comprobante salen de la sucursal elegida. Por eso los documentos aceptan `id_sucursal`.\n\nNace **activa** y **no** por defecto, igual que en la pantalla — salvo que sea la primera sucursal activa de ese proveedor, y entonces queda por defecto para que la emisión no tenga que adivinar. Con `por_defecto` en `true` se marca directamente, y la que lo estuviera se desmarca sola.", "x-azur-visibilidad": "publico", "x-azur-tipo": "escritura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del proveedor." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Clave que usted inventa para esta operación. Si reintenta con la misma clave, se devuelve el resultado original en vez de crear un segundo documento. Se recuerda 24 horas. **Mándela siempre en lo que escriba**: si se corta la conexión, es lo único que evita el duplicado." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntradaSucursal" } } } }, "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Registro" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/proveedor/{id}/sucursal/{sucursal}": { "put": { "tags": [ "Catálogos" ], "operationId": "editar_sucursal_proveedor", "summary": "Editar una sucursal de un proveedor", "description": "Cambia los datos de un local, lo marca por defecto, o lo da de baja y lo recupera. Solo se toca lo que mande.\n\n**Los comprobantes ya emitidos apuntan a esta sucursal por su id, no guardan copia de la dirección**: cambiarla aquí cambia lo que se ve al reimprimir esos documentos. Lo que ya se firmó y se envió al SRI no cambia — eso queda congelado en el XML autorizado.", "x-azur-visibilidad": "publico", "x-azur-tipo": "escritura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del proveedor." }, { "name": "sucursal", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id de la sucursal." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntradaSucursal" } } } }, "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Registro" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } }, "delete": { "tags": [ "Catálogos" ], "operationId": "eliminar_sucursal_proveedor", "summary": "Dar de baja una sucursal", "description": "La saca de las listas y ya no se puede facturar a ella.\n\n**No borra nada**: se marca como inactiva, porque los comprobantes que ya la usaron la vuelven a leer para reimprimirse. Se puede recuperar con `activa: true` en el PUT.\n\n**La sucursal por defecto no se puede dar de baja**: marque otra primero. Si tiene comprobantes emitidos sí se puede — el portal también lo permite — y la respuesta lo avisa diciendo cuántos son.", "x-azur-visibilidad": "publico", "x-azur-tipo": "escritura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del proveedor." }, { "name": "sucursal", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id de la sucursal." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Registro" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/inventario/existencias": { "get": { "tags": [ "Inventario" ], "operationId": "existencias", "summary": "Existencias por producto y bodega", "description": "Qué hay y dónde está.\n\nSolo aparecen los productos que controlan inventario: un servicio no tiene existencia.\n\n**Sin `id_bodega`, `existencias` es la SUMA de todas las bodegas del establecimiento**; con `id_bodega`, es solo la de esa bodega. La respuesta lo dice siempre en `alcance` (`tipo`: `establecimiento` o `bodega`, con `id_bodega` y `bodega`), para que el número nunca sea ambiguo. Si la empresa tiene varias bodegas, el agregado no es la existencia de ninguna de ellas.\n\n`bajo_minimo` se compara contra el número del alcance pedido.", "x-azur-visibilidad": "publico", "x-azur-tipo": "lectura", "parameters": [ { "name": "buscar", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Código o nombre del producto." }, { "name": "id_bodega", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Existencias de UNA bodega. Sale de /inventario/bodegas. Si no es del establecimiento de la credencial, la llamada devuelve 404." }, { "name": "solo_con_stock", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Omitir los que están en cero." }, { "name": "pagina", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Página, empezando en 1." }, { "name": "limite", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Cuántos por página, máximo 100." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Listado" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/inventario/bodegas": { "get": { "tags": [ "Inventario" ], "operationId": "bodegas", "summary": "Bodegas del establecimiento", "description": "Las bodegas activas sobre las que se puede mover mercadería. Hace falta el id de una para cualquier movimiento.\n\n`por_defecto` marca la predeterminada: solo hay una por establecimiento, y es a la que van los movimientos que no dicen bodega.", "x-azur-visibilidad": "publico", "x-azur-tipo": "lectura", "parameters": [ { "name": "buscar", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Nombre o id de la bodega." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Listado" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/inventario/bodega": { "post": { "tags": [ "Inventario" ], "operationId": "crear_bodega", "summary": "Crear una bodega", "description": "Da de alta una bodega en el establecimiento de la credencial.\n\nLo único obligatorio es el nombre, igual que en el portal. Nace **activa** y **no predeterminada**.\n\nSi ya hay otra bodega activa con ese nombre **no se rechaza** -el portal lo permite-, pero la respuesta trae un aviso.", "x-azur-visibilidad": "publico", "x-azur-tipo": "escritura", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntradaBodega" } } } }, "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Registro" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/inventario/bodega/{id}": { "put": { "tags": [ "Inventario" ], "operationId": "editar_bodega", "summary": "Editar una bodega", "description": "Nombre, bodega predeterminada y activar o desactivar. **Lo que no se manda no se toca.**\n\nSolo puede haber UNA bodega predeterminada por establecimiento: al marcar una, la anterior se desmarca sola.\n\n**Desactivar tiene dos frenos**, los mismos que la pantalla web:\n\n- si dentro todavía queda mercadería (entradas menos salidas distinto de cero), se rechaza con `datos_invalidos`. Apagar una bodega con existencia deja un inventario que no cuadra con nada;\n- la bodega **predeterminada** no se desactiva: marque otra primero.", "x-azur-visibilidad": "publico", "x-azur-tipo": "escritura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id de la bodega." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntradaBodega" } } } }, "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Registro" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/producto/categoria": { "post": { "tags": [ "Búsqueda" ], "operationId": "crear_categoria", "summary": "Crear una categoría de producto", "description": "Da de alta una categoría en el establecimiento de la credencial. Lo único obligatorio es el nombre.\n\nLas categorías admiten **jerarquía** por `id_categoriapadre`; sin él la categoría cuelga de la raíz, que es como las crea el portal.\n\nLa imagen de la categoría no se puede poner por aquí: en el portal se sube como fichero y esta API habla JSON.", "x-azur-visibilidad": "publico", "x-azur-tipo": "escritura", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntradaCategoria" } } } }, "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Registro" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/producto/categoria/{id}": { "put": { "tags": [ "Búsqueda" ], "operationId": "editar_categoria", "summary": "Editar una categoría de producto", "description": "Nombre, categoría padre, categoría predeterminada y activar o desactivar. **Lo que no se manda no se toca.**\n\n**El árbol se protege**: una categoría no puede ser su propio padre ni colgar de una de sus descendientes. Se rechaza con `datos_invalidos`.\n\n**Desactivar se rechaza** si la categoría es la predeterminada, si tiene productos activos dentro o si tiene categorías hijas activas: en los tres casos quedaría algo apuntando a una categoría que ya no se lista.", "x-azur-visibilidad": "publico", "x-azur-tipo": "escritura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id de la categoría." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntradaCategoria" } } } }, "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Registro" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/inventario/kardex/{id}": { "get": { "tags": [ "Inventario" ], "operationId": "kardex", "summary": "Kardex de un producto", "description": "Todo lo que entró y salió de un producto, **en orden cronológico ascendente**, con el saldo después de cada movimiento. Es el rastro que explica por qué la existencia es la que es: cuando un número no cuadra, se mira aquí.\n\nEs exactamente lo que enseña la pantalla de kárdex del portal: las mismas líneas, el mismo orden y el mismo saldo.\n\n**Sin `id_bodega` el kárdex es el agregado del establecimiento**; con él, el de esa bodega. Lo dice `filtros.alcance`.\n\n**El dinero depende del método de costeo de la empresa**, que viene en `costeo`: con «último costo» (el de casi todas las cuentas) no hay historia de costos y el valorizado es orientativo; con promedio ponderado o FIFO el saldo en dinero reproduce el libro. La cantidad es la misma en los tres.\n\n**Viene paginado**: un producto con años de movimientos no cabe en una respuesta. El saldo con el que arranca cada página se calcula, no se supone, así que la página 3 empieza donde acabó la 2.\n\n`saldo_inicial` es lo que había ANTES de `desde`; sin `desde` viene en cero, porque entonces la lista ya empieza por el principio.", "x-azur-visibilidad": "publico", "x-azur-tipo": "lectura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del producto. Tiene que controlar inventario." }, { "name": "desde", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Fecha desde (aaaa-mm-dd). Marca el corte del saldo inicial." }, { "name": "hasta", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Fecha hasta (aaaa-mm-dd), incluida." }, { "name": "id_bodega", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Limitar a una bodega. Sin él, el establecimiento entero." }, { "name": "tipo", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Solo entradas (1) o solo salidas (2)." }, { "name": "pagina", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Página, empezando en 1." }, { "name": "limite", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Cuántos por página. Por defecto 25, máximo 200." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Listado" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/inventario/ingreso": { "post": { "tags": [ "Inventario" ], "operationId": "inventario_ingreso", "summary": "Registrar un ingreso", "description": "Entra mercadería a una bodega: una compra, una devolución de un cliente, una producción terminada.\n\nSi la cuenta tiene contabilidad activa, el movimiento **genera su asiento solo**: no hay que crearlo aparte.\n\n**Un movimiento no se deshace.** Para corregir uno equivocado se hace otro en sentido contrario, y los dos quedan en el kardex.", "x-azur-visibilidad": "publico", "x-azur-tipo": "escritura", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Clave que usted inventa para esta operación. Si reintenta con la misma clave, se devuelve el resultado original en vez de crear un segundo documento. Se recuerda 24 horas. **Mándela siempre en lo que escriba**: si se corta la conexión, es lo único que evita el duplicado." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntradaMovimiento" } } } }, "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Registro" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/inventario/salida": { "post": { "tags": [ "Inventario" ], "operationId": "inventario_salida", "summary": "Registrar un salida", "description": "Sale mercadería de una bodega por algo que no es una venta: una baja, un consumo interno, una muestra.\n\nSi la cuenta tiene contabilidad activa, el movimiento **genera su asiento solo**: no hay que crearlo aparte.\n\n**Un movimiento no se deshace.** Para corregir uno equivocado se hace otro en sentido contrario, y los dos quedan en el kardex.", "x-azur-visibilidad": "publico", "x-azur-tipo": "escritura", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Clave que usted inventa para esta operación. Si reintenta con la misma clave, se devuelve el resultado original en vez de crear un segundo documento. Se recuerda 24 horas. **Mándela siempre en lo que escriba**: si se corta la conexión, es lo único que evita el duplicado." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntradaMovimiento" } } } }, "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Registro" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/inventario/transferencia": { "post": { "tags": [ "Inventario" ], "operationId": "inventario_transferencia", "summary": "Registrar una transferencia", "description": "Mueve mercadería de una bodega a otra. La existencia total no cambia, cambia dónde está.\n\nVan dos bodegas: `id_bodega` es de donde sale e `id_bodega_destino` a dónde llega.\n\nSi la cuenta tiene contabilidad activa, el movimiento **genera su asiento solo**: no hay que crearlo aparte.\n\n**Un movimiento no se deshace.** Para corregir uno equivocado se hace otro en sentido contrario, y los dos quedan en el kardex.", "x-azur-visibilidad": "publico", "x-azur-tipo": "escritura", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Clave que usted inventa para esta operación. Si reintenta con la misma clave, se devuelve el resultado original en vez de crear un segundo documento. Se recuerda 24 horas. **Mándela siempre en lo que escriba**: si se corta la conexión, es lo único que evita el duplicado." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntradaMovimiento" } } } }, "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Registro" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/inventario/ajuste": { "post": { "tags": [ "Inventario" ], "operationId": "inventario_ajuste", "summary": "Registrar un ajuste", "description": "Cuadra la existencia del sistema con la del conteo físico, después de un inventario. Cada línea lleva `tipo`: `aumentar` o `disminuir`.\n\nSi la cuenta tiene contabilidad activa, el movimiento **genera su asiento solo**: no hay que crearlo aparte.\n\n**Un movimiento no se deshace.** Para corregir uno equivocado se hace otro en sentido contrario, y los dos quedan en el kardex.", "x-azur-visibilidad": "publico", "x-azur-tipo": "escritura", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Clave que usted inventa para esta operación. Si reintenta con la misma clave, se devuelve el resultado original en vez de crear un segundo documento. Se recuerda 24 horas. **Mándela siempre en lo que escriba**: si se corta la conexión, es lo único que evita el duplicado." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntradaMovimiento" } } } }, "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Registro" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/contabilidad/cuentas": { "get": { "tags": [ "Contabilidad" ], "operationId": "cuentas_contables", "summary": "Plan de cuentas", "description": "El plan de cuentas de la empresa.\n\nCada cliente puede tener el suyo, así que **no dé por hecho ningún código**: las cuentas que aparezcan aquí son las únicas que sirven para un asiento. Solo se puede imputar sobre cuentas de movimiento; las de grupo no admiten saldo.\n\n**Requiere el módulo de contabilidad.** Sin él la llamada devuelve `sin_permiso`.", "x-azur-visibilidad": "publico", "x-azur-tipo": "lectura", "parameters": [ { "name": "buscar", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Código o nombre de la cuenta." }, { "name": "solo_movimiento", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Solo las que admiten asiento." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Listado" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/contabilidad/centros-costo": { "get": { "tags": [ "Contabilidad" ], "operationId": "centros_costo", "summary": "Centros de costo", "description": "Los centros de costo configurados.\n\nSon **opcionales**: si la cuenta no los usa, esto viene vacío y los asientos se hacen sin centro.\n\n**Requiere el módulo de contabilidad.** Sin él la llamada devuelve `sin_permiso`.", "x-azur-visibilidad": "publico", "x-azur-tipo": "lectura", "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Listado" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/contabilidad/asiento": { "post": { "tags": [ "Contabilidad" ], "operationId": "guardar_asiento", "summary": "Crear un asiento manual", "description": "Registra un asiento contable escrito a mano.\n\n**El debe y el haber tienen que ser iguales**, al centavo. Si no cuadran se rechaza con `datos_invalidos` y no queda nada a medias.\n\nEsto es para lo que no nace de un documento: una depreciación, un ajuste, un cierre. Facturas, compras y movimientos de inventario **ya generan su asiento solos** — si los vuelve a asentar aquí, los duplica.\n\n**Requiere el módulo de contabilidad.** Sin él la llamada devuelve `sin_permiso`.", "x-azur-visibilidad": "publico", "x-azur-tipo": "escritura", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Clave que usted inventa para esta operación. Si reintenta con la misma clave, se devuelve el resultado original en vez de crear un segundo documento. Se recuerda 24 horas. **Mándela siempre en lo que escriba**: si se corta la conexión, es lo único que evita el duplicado." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntradaAsiento" } } } }, "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Registro" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/contabilidad/asientos": { "get": { "tags": [ "Contabilidad" ], "operationId": "listar_asientos", "summary": "Listar asientos", "description": "Los asientos de un período, del más reciente al más antiguo.\n\n**Requiere el módulo de contabilidad.** Sin él la llamada devuelve `sin_permiso`.", "x-azur-visibilidad": "publico", "x-azur-tipo": "lectura", "parameters": [ { "name": "desde", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Fecha desde (aaaa-mm-dd)." }, { "name": "hasta", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Fecha hasta (aaaa-mm-dd)." }, { "name": "buscar", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Parte del concepto o del número." }, { "name": "pagina", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Página, empezando en 1." }, { "name": "limite", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Cuántos por página, máximo 100." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Listado" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/contabilidad/asiento/{id}": { "get": { "tags": [ "Contabilidad" ], "operationId": "ver_asiento", "summary": "Consultar un asiento", "description": "Devuelve un asiento con todas sus líneas.\n\n**Requiere el módulo de contabilidad.** Sin él la llamada devuelve `sin_permiso`.", "x-azur-visibilidad": "publico", "x-azur-tipo": "lectura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del asiento." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Registro" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/reportes/ats": { "get": { "tags": [ "Reportes" ], "operationId": "reporte_ats", "summary": "ATS del mes (XML del SRI)", "description": "El **Anexo Transaccional Simplificado** de un mes, en el XML que se sube tal cual a SRI en línea. Lo genera el mismo motor que el botón del portal, con sus mismas reglas.\n\nSi alguna compra del mes no tiene documento de sustento registrado, no se genera y se devuelve `datos_invalidos` diciendo **qué compra** hay que arreglar: eso no es un fallo de la API, es el ATS avisando.\n\nCon `base64=1` viaja dentro del JSON de siempre.", "x-azur-visibilidad": "publico", "x-azur-tipo": "lectura", "parameters": [ { "name": "anio", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Año. Por defecto, el actual." }, { "name": "mes", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Mes, del 1 al 12. Por defecto, el actual." }, { "name": "base64", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "A 1 para recibirlo dentro del JSON." } ], "responses": { "200": { "description": "El fichero. Con `base64=1`, el JSON de siempre.", "content": { "application/xml": { "schema": { "type": "string", "format": "binary" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Archivo" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta, o el fichero todavía no existe.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta, o el fichero todavía no existe.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/reportes/ventas": { "get": { "tags": [ "Reportes" ], "operationId": "reporte_ventas", "summary": "Ventas agrupadas", "description": "Las ventas del periodo agrupadas por `dia`, `mes`, `cliente`, `producto` o `vendedor`, con el total ya sumado.\n\n**Solo cuenta lo autorizado por el SRI**, igual que el reporte del portal: los borradores y los rechazados no suman, o el reporte no cuadraría con ninguna declaración.\n\nAgrupando por producto se suma la **línea**, así que además viene la cantidad, el subtotal y el IVA; ahí `documentos` es por fila y no se totaliza, porque una misma factura aparece en varias.\n\nSin fechas, el mes en curso. Un vendedor solo ve lo suyo.", "x-azur-visibilidad": "publico", "x-azur-tipo": "lectura", "parameters": [ { "name": "agrupar", "in": "query", "required": false, "schema": { "type": "string" }, "description": "`dia` (por defecto), `mes`, `cliente`, `producto` o `vendedor`." }, { "name": "desde", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Desde (aaaa-mm-dd). Por defecto, el 1 de este mes." }, { "name": "hasta", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Hasta (aaaa-mm-dd). Por defecto, fin de este mes." }, { "name": "id_cliente", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Solo las ventas a ese cliente." }, { "name": "id_vendedor", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Solo las de ese vendedor." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Listado" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/reportes/compras": { "get": { "tags": [ "Reportes" ], "operationId": "reporte_compras", "summary": "Compras agrupadas", "description": "Las compras del periodo agrupadas por `dia`, `mes`, `proveedor` o `producto`.\n\nAquí no hay estado del SRI que mirar: la compra es un documento que emitió otro y en AZUR solo se registra.", "x-azur-visibilidad": "publico", "x-azur-tipo": "lectura", "parameters": [ { "name": "agrupar", "in": "query", "required": false, "schema": { "type": "string" }, "description": "`dia` (por defecto), `mes`, `proveedor` o `producto`." }, { "name": "desde", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Desde (aaaa-mm-dd)." }, { "name": "hasta", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Hasta (aaaa-mm-dd)." }, { "name": "id_proveedor", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Solo las compras a ese proveedor." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Listado" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/cartera/{cual}/documentos": { "get": { "tags": [ "Cartera" ], "operationId": "cartera_documentos", "summary": "Documentos con saldo", "description": "Los documentos que todavía deben dinero, del más vencido al menos, con `dias_vencido` calculado: positivo si ya venció, negativo si aún le quedan días.\n\nPor defecto solo salen los que tienen saldo; con `pendientes=0` salen también los ya saldados, que es lo que hace falta para conciliar.\n\n**Si esta cuenta no tiene la cartera activada, esto viene vacío** y no está roto: el módulo se activa por establecimiento.", "x-azur-visibilidad": "publico", "x-azur-tipo": "lectura", "parameters": [ { "name": "cual", "in": "path", "required": true, "schema": { "type": "string" }, "description": "`cobrar` para lo que le deben sus clientes, `pagar` para lo que usted debe a sus proveedores." }, { "name": "id_cliente", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Solo los de ese cliente." }, { "name": "id_proveedor", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Solo los de ese proveedor." }, { "name": "vencidos", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "A 1 solo los que ya pasaron su fecha de vencimiento." }, { "name": "pendientes", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "A 0 para incluir los ya saldados." }, { "name": "desde", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Fecha del documento desde (aaaa-mm-dd)." }, { "name": "hasta", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Fecha del documento hasta (aaaa-mm-dd)." }, { "name": "pagina", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Página, empezando en 1." }, { "name": "limite", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Cuántos por página, máximo 100." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Listado" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/cartera/{cual}/personas": { "get": { "tags": [ "Cartera" ], "operationId": "cartera_personas", "summary": "Cuánto debe cada uno", "description": "El saldo agrupado por cliente —o por proveedor—, de mayor a menor, con cuántos documentos lo componen. Es la lista con la que se sale a cobrar.", "x-azur-visibilidad": "publico", "x-azur-tipo": "lectura", "parameters": [ { "name": "cual", "in": "path", "required": true, "schema": { "type": "string" }, "description": "`cobrar` para lo que le deben sus clientes, `pagar` para lo que usted debe a sus proveedores." }, { "name": "pagina", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Página, empezando en 1." }, { "name": "limite", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Cuántos por página, máximo 100." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Listado" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/cartera/{cual}/movimientos": { "get": { "tags": [ "Cartera" ], "operationId": "cartera_movimientos", "summary": "Estado de cuenta", "description": "El libro, una fila por partida y en orden, con **debe**, **haber** y qué es cada movimiento: el cargo del documento, una nota de débito —que suma—, una nota de crédito, un cobro o una retención que le hicieron.\n\nAquí no se agrupa ni se esconde nada: el saldo que se devuelve es la suma de todo lo filtrado, no solo de la página que se ve.\n\nFiltre por `id_cliente` —o `id_proveedor`— para el estado de cuenta de uno solo.", "x-azur-visibilidad": "publico", "x-azur-tipo": "lectura", "parameters": [ { "name": "cual", "in": "path", "required": true, "schema": { "type": "string" }, "description": "`cobrar` para lo que le deben sus clientes, `pagar` para lo que usted debe a sus proveedores." }, { "name": "id_cliente", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Estado de cuenta de ese cliente." }, { "name": "id_proveedor", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Estado de cuenta de ese proveedor." }, { "name": "tipo_documento", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Código del tipo de documento: `01`, `02`, `03`…" }, { "name": "id_comprobante", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Solo las partidas de ese documento." }, { "name": "desde", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Desde (aaaa-mm-dd)." }, { "name": "hasta", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Hasta (aaaa-mm-dd)." }, { "name": "pagina", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Página, empezando en 1." }, { "name": "limite", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Cuántos por página, máximo 200." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Listado" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/cartera/{cual}/movimiento/{id}": { "delete": { "tags": [ "Cartera" ], "operationId": "cartera_eliminar_movimiento", "summary": "Deshacer un cobro o un pago", "description": "Borra el recibo y devuelve el saldo al documento; con contabilidad, también deshace su asiento.\n\n**Solo recibos de cobro o de pago.** Una nota de crédito o una retención también viven en este libro, pero se deshacen anulando su propio comprobante: borrarlas desde aquí dejaría el comprobante emitido por un lado y la cartera por otro.", "x-azur-visibilidad": "publico", "x-azur-tipo": "escritura", "parameters": [ { "name": "cual", "in": "path", "required": true, "schema": { "type": "string" }, "description": "`cobrar` para lo que le deben sus clientes, `pagar` para lo que usted debe a sus proveedores." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del movimiento." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Documento" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/factura/{id}/cobros": { "get": { "tags": [ "Cartera" ], "operationId": "cobros_factura", "summary": "Movimientos de cartera de una factura", "description": "Lo cargado, lo abonado y lo que queda, con cada movimiento detallado. `eliminable` dice cuáles se pueden deshacer.\n\nVale igual `/notaventa/{id}/cobros`, y `/compra/{id}/pagos` y `/liquidacion/{id}/pagos` para lo que usted debe.", "x-azur-visibilidad": "publico", "x-azur-tipo": "lectura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id de la factura." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Listado" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/factura/{id}/cobro": { "post": { "tags": [ "Cartera" ], "operationId": "cobrar_factura", "summary": "Registrar un cobro", "description": "Registra el abono, actualiza el saldo y la marca de pagada del documento y —si la cuenta tiene Contabilidad— genera el asiento: debe la caja o el banco donde entra el dinero, haber la cuenta por cobrar del cliente.\n\n**No deja cobrar más que el saldo.** Tampoco con el ejercicio contable cerrado ni sin las automatizaciones contables configuradas: son las mismas guardas del portal.\n\nCon `forma: cheque` el cobro queda además en cheques pendientes hasta que se haga efectivo.\n\nVale igual `/notaventa/{id}/cobro`; para lo que usted paga, `/compra/{id}/pago` y `/liquidacion/{id}/pago`.", "x-azur-visibilidad": "publico", "x-azur-tipo": "escritura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id de la factura." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Clave que usted inventa para esta operación. Si reintenta con la misma clave, se devuelve el resultado original en vez de crear un segundo documento. Se recuerda 24 horas. **Mándela siempre en lo que escriba**: si se corta la conexión, es lo único que evita el duplicado." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "valor" ], "properties": { "valor": { "type": "number", "description": "Cuánto se cobra. No puede pasar del saldo." }, "forma": { "type": "string", "description": "`efectivo` (por defecto), `tarjeta`, `transferencia` o `cheque`." }, "fecha": { "type": "string", "description": "aaaa-mm-dd. Por defecto, hoy." }, "concepto": { "type": "string", "description": "Si no se pone, se arma solo con el número del documento." }, "observacion": { "type": "string" }, "id_banco": { "type": "integer", "description": "Banco o caja DONDE ENTRA el dinero. Es la cuenta que se carga en el asiento." }, "banco_origen": { "type": "integer", "description": "Banco del que sale el dinero, para la referencia." }, "referencia": { "type": "string", "description": "Número de la transferencia o del depósito." }, "numero_cheque": { "type": "string" }, "lote_tarjeta": { "type": "string" }, "marca_tarjeta": { "type": "string" } } } } } }, "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Documento" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/notaventa/{id}/cobros": { "get": { "tags": [ "Cartera" ], "operationId": "cobros_notaventa", "summary": "Movimientos de cartera de una nota de venta", "description": "Lo cargado, lo abonado y lo que queda, con cada movimiento detallado. `eliminable` dice cuáles se pueden deshacer.\n\nVale igual `/notaventa/{id}/cobros`, y `/compra/{id}/pagos` y `/liquidacion/{id}/pagos` para lo que usted debe.", "x-azur-visibilidad": "publico", "x-azur-tipo": "lectura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id de la nota de venta." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Listado" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/notaventa/{id}/cobro": { "post": { "tags": [ "Cartera" ], "operationId": "cobrar_notaventa", "summary": "Registrar un cobro de una nota de venta", "description": "Registra el abono, actualiza el saldo y la marca de pagada del documento y —si la cuenta tiene Contabilidad— genera el asiento: debe la caja o el banco donde entra el dinero, haber la cuenta por cobrar del cliente.\n\n**No deja cobrar más que el saldo.** Tampoco con el ejercicio contable cerrado ni sin las automatizaciones contables configuradas: son las mismas guardas del portal.\n\nCon `forma: cheque` el cobro queda además en cheques pendientes hasta que se haga efectivo.\n\nVale igual `/notaventa/{id}/cobro`; para lo que usted paga, `/compra/{id}/pago` y `/liquidacion/{id}/pago`.", "x-azur-visibilidad": "publico", "x-azur-tipo": "escritura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id de la nota de venta." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Clave que usted inventa para esta operación. Si reintenta con la misma clave, se devuelve el resultado original en vez de crear un segundo documento. Se recuerda 24 horas. **Mándela siempre en lo que escriba**: si se corta la conexión, es lo único que evita el duplicado." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "valor" ], "properties": { "valor": { "type": "number", "description": "Cuánto se cobra. No puede pasar del saldo." }, "forma": { "type": "string", "description": "`efectivo` (por defecto), `tarjeta`, `transferencia` o `cheque`." }, "fecha": { "type": "string", "description": "aaaa-mm-dd. Por defecto, hoy." }, "concepto": { "type": "string", "description": "Si no se pone, se arma solo con el número del documento." }, "observacion": { "type": "string" }, "id_banco": { "type": "integer", "description": "Banco o caja DONDE ENTRA el dinero. Es la cuenta que se carga en el asiento." }, "banco_origen": { "type": "integer", "description": "Banco del que sale el dinero, para la referencia." }, "referencia": { "type": "string", "description": "Número de la transferencia o del depósito." }, "numero_cheque": { "type": "string" }, "lote_tarjeta": { "type": "string" }, "marca_tarjeta": { "type": "string" } } } } } }, "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Documento" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/compra/{id}/pagos": { "get": { "tags": [ "Cartera" ], "operationId": "pagos_compra", "summary": "Movimientos de cartera de una compra", "description": "Lo cargado, lo abonado y lo que queda, con cada movimiento detallado. `eliminable` dice cuáles se pueden deshacer.\n\nVale igual `/notaventa/{id}/cobros`, y `/compra/{id}/pagos` y `/liquidacion/{id}/pagos` para lo que usted debe.", "x-azur-visibilidad": "publico", "x-azur-tipo": "lectura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id de la compra." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Listado" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/compra/{id}/pago": { "post": { "tags": [ "Cartera" ], "operationId": "pagar_compra", "summary": "Registrar un pago de una compra", "description": "Registra el abono, actualiza el saldo y la marca de pagada del documento y —si la cuenta tiene Contabilidad— genera el asiento: debe la caja o el banco donde entra el dinero, haber la cuenta por cobrar del cliente.\n\n**No deja cobrar más que el saldo.** Tampoco con el ejercicio contable cerrado ni sin las automatizaciones contables configuradas: son las mismas guardas del portal.\n\nCon `forma: cheque` el cobro queda además en cheques pendientes hasta que se haga efectivo.\n\nVale igual `/notaventa/{id}/cobro`; para lo que usted paga, `/compra/{id}/pago` y `/liquidacion/{id}/pago`.", "x-azur-visibilidad": "publico", "x-azur-tipo": "escritura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id de la compra." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Clave que usted inventa para esta operación. Si reintenta con la misma clave, se devuelve el resultado original en vez de crear un segundo documento. Se recuerda 24 horas. **Mándela siempre en lo que escriba**: si se corta la conexión, es lo único que evita el duplicado." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "valor" ], "properties": { "valor": { "type": "number", "description": "Cuánto se cobra. No puede pasar del saldo." }, "forma": { "type": "string", "description": "`efectivo` (por defecto), `tarjeta`, `transferencia` o `cheque`." }, "fecha": { "type": "string", "description": "aaaa-mm-dd. Por defecto, hoy." }, "concepto": { "type": "string", "description": "Si no se pone, se arma solo con el número del documento." }, "observacion": { "type": "string" }, "id_banco": { "type": "integer", "description": "Banco o caja DONDE ENTRA el dinero. Es la cuenta que se carga en el asiento." }, "banco_origen": { "type": "integer", "description": "Banco del que sale el dinero, para la referencia." }, "referencia": { "type": "string", "description": "Número de la transferencia o del depósito." }, "numero_cheque": { "type": "string" }, "lote_tarjeta": { "type": "string" }, "marca_tarjeta": { "type": "string" } } } } } }, "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Documento" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/liquidacion/{id}/pagos": { "get": { "tags": [ "Cartera" ], "operationId": "pagos_liquidacion", "summary": "Movimientos de cartera de una liquidación de compra", "description": "Lo cargado, lo abonado y lo que queda, con cada movimiento detallado. `eliminable` dice cuáles se pueden deshacer.\n\nVale igual `/notaventa/{id}/cobros`, y `/compra/{id}/pagos` y `/liquidacion/{id}/pagos` para lo que usted debe.", "x-azur-visibilidad": "publico", "x-azur-tipo": "lectura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id de la liquidación de compra." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Listado" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/liquidacion/{id}/pago": { "post": { "tags": [ "Cartera" ], "operationId": "pagar_liquidacion", "summary": "Registrar un pago de una liquidación de compra", "description": "Registra el abono, actualiza el saldo y la marca de pagada del documento y —si la cuenta tiene Contabilidad— genera el asiento: debe la caja o el banco donde entra el dinero, haber la cuenta por cobrar del cliente.\n\n**No deja cobrar más que el saldo.** Tampoco con el ejercicio contable cerrado ni sin las automatizaciones contables configuradas: son las mismas guardas del portal.\n\nCon `forma: cheque` el cobro queda además en cheques pendientes hasta que se haga efectivo.\n\nVale igual `/notaventa/{id}/cobro`; para lo que usted paga, `/compra/{id}/pago` y `/liquidacion/{id}/pago`.", "x-azur-visibilidad": "publico", "x-azur-tipo": "escritura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id de la liquidación de compra." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Clave que usted inventa para esta operación. Si reintenta con la misma clave, se devuelve el resultado original en vez de crear un segundo documento. Se recuerda 24 horas. **Mándela siempre en lo que escriba**: si se corta la conexión, es lo único que evita el duplicado." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "valor" ], "properties": { "valor": { "type": "number", "description": "Cuánto se cobra. No puede pasar del saldo." }, "forma": { "type": "string", "description": "`efectivo` (por defecto), `tarjeta`, `transferencia` o `cheque`." }, "fecha": { "type": "string", "description": "aaaa-mm-dd. Por defecto, hoy." }, "concepto": { "type": "string", "description": "Si no se pone, se arma solo con el número del documento." }, "observacion": { "type": "string" }, "id_banco": { "type": "integer", "description": "Banco o caja DONDE ENTRA el dinero. Es la cuenta que se carga en el asiento." }, "banco_origen": { "type": "integer", "description": "Banco del que sale el dinero, para la referencia." }, "referencia": { "type": "string", "description": "Número de la transferencia o del depósito." }, "numero_cheque": { "type": "string" }, "lote_tarjeta": { "type": "string" }, "marca_tarjeta": { "type": "string" } } } } } }, "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Documento" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/recibidos": { "get": { "tags": [ "Recibidos" ], "operationId": "listar_recibidos", "summary": "Listar documentos recibidos", "description": "Los comprobantes que **le han emitido a usted** y que ya están importados en AZUR: facturas de proveedores, notas de crédito, retenciones que le hicieron, liquidaciones y guías.\n\nCada fila trae la clave de acceso, el tipo, el número, la fecha, el emisor (RUC y razón social), los importes y **`vinculado`**: si ese documento ya se convirtió en una compra de AZUR. Ése es el campo con el que se sabe qué falta por registrar.\n\nUn documento recibido es de la **empresa**, no de un establecimiento: la tabla no guarda establecimiento, así que aquí no se filtra por él.", "x-azur-visibilidad": "publico", "x-azur-tipo": "lectura", "parameters": [ { "name": "tipo", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Uno o varios códigos del SRI separados por coma: `01`, `03`, `04`, `05`, `06`, `07`." }, { "name": "desde", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Fecha de emisión desde (aaaa-mm-dd)." }, { "name": "hasta", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Fecha de emisión hasta (aaaa-mm-dd)." }, { "name": "buscar", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Parte del RUC o del nombre del emisor, del secuencial o de la clave de acceso." }, { "name": "vinculados", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "A 1 solo los que ya son compra en AZUR; a 0 solo los que faltan por registrar." }, { "name": "pagina", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Página, empezando en 1." }, { "name": "limite", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Cuántos por página, máximo 100." }, { "name": "modificado_desde", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Devuelve solo lo que CAMBIÓ desde ese momento (aaaa-mm-dd o aaaa-mm-dd hh:mm:ss), ordenado de más antiguo a más reciente. Es lo que hay que usar para sincronizar: a diferencia de «desde», que mira la fecha de emisión, esto sí devuelve una factura vieja que se acaba de anular o corregir." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Para seguir por donde se quedó. Se coge tal cual de «siguiente_cursor» de la llamada anterior; cuando venga vacío es que ya está al día. Con cursor NO se usa «pagina»: paginar por número se descoloca en cuanto entran documentos nuevos entre página y página." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Listado" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/recibidos/importar": { "post": { "tags": [ "Recibidos" ], "operationId": "importar_recibido", "summary": "Importar un recibido desde el SRI", "description": "Va al SRI con la clave de acceso, se baja el XML autorizado, lo guarda y lo registra como documento recibido.\n\n**Tarda lo que tarde el SRI**: es una llamada real a su servicio, no una lectura de la base. Si ese comprobante ya estaba importado no se vuelve a bajar: responde con `ya_estaba` y la ficha que había.", "x-azur-visibilidad": "publico", "x-azur-tipo": "escritura", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Clave que usted inventa para esta operación. Si reintenta con la misma clave, se devuelve el resultado original en vez de crear un segundo documento. Se recuerda 24 horas. **Mándela siempre en lo que escriba**: si se corta la conexión, es lo único que evita el duplicado." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "claveacceso" ], "properties": { "claveacceso": { "type": "string", "description": "Los 49 dígitos de la clave de acceso del comprobante." } } } } } }, "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Documento" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/recibidos/{clave}": { "get": { "tags": [ "Recibidos" ], "operationId": "ver_recibido", "summary": "Consultar un documento recibido", "description": "La ficha completa: emisor, importes desglosados, autorización, los impuestos que trae el XML y —en una retención— el sustento, que dice de qué documento suyo habla.", "x-azur-visibilidad": "publico", "x-azur-tipo": "lectura", "parameters": [ { "name": "clave", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Clave de acceso (49 dígitos)." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Documento" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/recibidos/{clave}/xml": { "get": { "tags": [ "Recibidos" ], "operationId": "xml_recibido", "summary": "XML de un documento recibido", "description": "El XML autorizado tal cual lo emitió su proveedor. Con `base64=1` viaja dentro del JSON de siempre.", "x-azur-visibilidad": "publico", "x-azur-tipo": "lectura", "parameters": [ { "name": "clave", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Clave de acceso (49 dígitos)." }, { "name": "base64", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "A 1 para recibirlo dentro del JSON." } ], "responses": { "200": { "description": "El fichero. Con `base64=1`, el JSON de siempre.", "content": { "application/xml": { "schema": { "type": "string", "format": "binary" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Archivo" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta, o el fichero todavía no existe.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta, o el fichero todavía no existe.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/recibidos/{clave}/pdf": { "get": { "tags": [ "Recibidos" ], "operationId": "pdf_recibido", "summary": "PDF de un documento recibido", "description": "El comprobante en PDF. No es un fichero guardado: se arma leyendo el XML del emisor, igual que la vista del portal.", "x-azur-visibilidad": "publico", "x-azur-tipo": "lectura", "parameters": [ { "name": "clave", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Clave de acceso (49 dígitos)." }, { "name": "base64", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "A 1 para recibirlo dentro del JSON." } ], "responses": { "200": { "description": "El fichero. Con `base64=1`, el JSON de siempre.", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Archivo" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta, o el fichero todavía no existe.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta, o el fichero todavía no existe.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/recibidos/{clave}/compra": { "post": { "tags": [ "Recibidos" ], "operationId": "recibido_a_compra", "summary": "Convertir un recibido en compra", "description": "Lee el XML del proveedor y da de alta la **compra** en AZUR con sus líneas y sus impuestos; con el módulo de Contabilidad, también su asiento.\n\nCorta antes de crear nada si el ejercicio contable está cerrado o si faltan las automatizaciones contables de compra: son las mismas guardas que el portal.\n\nLa empresa, el establecimiento, el punto de emisión y el ambiente salen de la credencial y **no se aceptan en el cuerpo**.", "x-azur-visibilidad": "publico", "x-azur-tipo": "escritura", "parameters": [ { "name": "clave", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Clave de acceso (49 dígitos)." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Clave que usted inventa para esta operación. Si reintenta con la misma clave, se devuelve el resultado original en vez de crear un segundo documento. Se recuerda 24 horas. **Mándela siempre en lo que escriba**: si se corta la conexión, es lo único que evita el duplicado." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "sustento": { "type": "string", "description": "Código de sustento tributario del SRI. Por defecto `01`, crédito tributario para IVA." }, "iva": { "type": "string", "description": "Tarifa de IVA a aplicar, si hay que forzarla." }, "es_gasto": { "type": "boolean", "description": "A `true` si la compra es gasto y no inventario." }, "id_cuenta_contable": { "type": "integer", "description": "Cuenta del plan a la que imputar." }, "nombre_cuenta_contable": { "type": "string", "description": "Nombre de esa cuenta." } } } } } }, "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Documento" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/webhooks": { "get": { "tags": [ "Webhooks" ], "operationId": "listar_webhooks", "summary": "Listar webhooks", "description": "Los avisos registrados en esta cuenta, con cuántos envíos les fallaron.", "x-azur-visibilidad": "publico", "x-azur-tipo": "lectura", "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Listado" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } }, "post": { "tags": [ "Webhooks" ], "operationId": "registrar_webhook", "summary": "Registrar un webhook", "description": "AZUR llamará a esa dirección cuando un comprobante cambie de estado, así no hay que estar preguntando.\n\n**Verifique la firma.** Cada envío lleva la cabecera `X-Azur-Firma` con un HMAC-SHA256 del cuerpo usando el secreto que se devuelve al registrar — que se muestra **una sola vez**. Sin comprobarla, cualquiera que sepa su URL puede fingir ser AZUR.\n\nConteste 2xx rápido; si falla, se reintenta con espera creciente. El mismo aviso puede llegar dos veces: use el `id` del documento para no procesarlo dos veces.", "x-azur-visibilidad": "publico", "x-azur-tipo": "escritura", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntradaWebhook" } } } }, "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Registro" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/webhooks/{id}": { "delete": { "tags": [ "Webhooks" ], "operationId": "borrar_webhook", "summary": "Quitar un webhook", "description": "Deja de avisar a esa dirección. No afecta a los documentos.", "x-azur-visibilidad": "publico", "x-azur-tipo": "escritura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del webhook." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Registro" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } }, "/webhooks/{id}/envios": { "get": { "tags": [ "Webhooks" ], "operationId": "envios_webhook", "summary": "Últimos envíos de un webhook", "description": "Qué se intentó mandar, cuándo y con qué respuesta. Es por donde se empieza cuando un aviso «no llegó».", "x-azur-visibilidad": "publico", "x-azur-tipo": "lectura", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id del webhook." } ], "responses": { "200": { "description": "Correcto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Listado" } } } }, "401": { "description": "La credencial falta, no vale o fue revocada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "credencial_invalida", "mensaje": "La credencial falta, no vale o fue revocada.", "reintentable": false } } } } }, "402": { "description": "Se acabaron los comprobantes del plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "cupo_agotado", "mensaje": "Se acabaron los comprobantes del plan.", "reintentable": false } } } } }, "404": { "description": "No existe en su cuenta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "no_encontrado", "mensaje": "No existe en su cuenta.", "reintentable": false } } } } }, "409": { "description": "El documento ya no admite esa operación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "documento_no_editable", "mensaje": "El documento ya no admite esa operación.", "reintentable": false } } } } }, "422": { "description": "Los datos enviados no son válidos. El detalle dice qué falla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "datos_invalidos", "mensaje": "Los datos enviados no son válidos. El detalle dice qué falla.", "reintentable": false } } } } }, "429": { "description": "Demasiadas peticiones. Espere y reintente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "demasiadas_peticiones", "mensaje": "Demasiadas peticiones. Espere y reintente.", "reintentable": true } } } } }, "500": { "description": "Fallo interno. Se puede reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "ok": false, "error": { "codigo": "error_interno", "mensaje": "Fallo interno. Se puede reintentar.", "reintentable": true } } } } } } } } }, "components": { "securitySchemes": { "api_key_emision": { "type": "apiKey", "in": "header", "name": "X-Api-Key", "description": "Solo para «Emisión directa»: el `api_key` del punto de emisión (empieza con `API_`). También puede ir en el campo `api_key` del cuerpo JSON; si viene en los dos, vale el del cuerpo." }, "credencial": { "type": "apiKey", "in": "header", "name": "X-Api-Key", "description": "Credencial de la cuenta. Empieza por `azur_live_` en producción y por `azur_test_` en pruebas. También se acepta como `Authorization: Bearer`. El ambiente va fijado en la credencial y no se puede cambiar en la llamada. La crea el dueño de la cuenta en su menú de usuario → Credenciales API, con permisos (por ejemplo «Consultar comprobantes»), IP autorizadas y vencimiento opcionales. Si la operación no está entre sus permisos responde `sin_permiso`." } }, "schemas": { "Error": { "type": "object", "properties": { "ok": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "codigo": { "type": "string", "description": "Código estable. Ramifique por esto, no por el mensaje." }, "mensaje": { "type": "string", "description": "Texto para enseñárselo a una persona." }, "reintentable": { "type": "boolean", "description": "Si tiene sentido volver a intentarlo." }, "detalle": { "type": "object" } } } } }, "Documento": { "type": "object", "properties": { "ok": { "type": "boolean" }, "datos": { "type": "object", "properties": { "id": { "type": "integer" }, "numero": { "type": "string", "example": "001-001-000000123" }, "fecha": { "type": "string" }, "total": { "type": "number" }, "estado": { "type": "string", "description": "borrador · en proceso · autorizado · error al firmar" }, "es_borrador": { "type": "boolean" }, "claveacceso": { "type": "string" } } }, "avisos": { "type": "array", "items": { "type": "string" }, "description": "Cosas que conviene saber aunque la operación saliera bien." } } }, "Busqueda": { "type": "object", "properties": { "ok": { "type": "boolean" }, "datos": { "type": "object", "properties": { "total": { "type": "integer" }, "unico": { "type": "boolean", "description": "**true solo si hay UN resultado.** Si es false, hay que elegir: no dé por buena la primera fila." }, "hay_mas": { "type": "boolean" } } } } }, "LotesProducto": { "type": "object", "properties": { "ok": { "type": "boolean" }, "datos": { "type": "object", "properties": { "id_producto": { "type": "integer" }, "codigo": { "type": "string" }, "nombre": { "type": "string" }, "trazabilidad": { "type": "integer", "enum": [ 0, 1, 2 ], "description": "0 no lleva · 1 lote · 2 serie / IMEI." }, "lleva_lote": { "type": "boolean" }, "lleva_serie": { "type": "boolean" }, "controla_caducidad": { "type": "boolean", "description": "Si hay que enseñar y pedir la fecha de caducidad." }, "empresa_lleva_lotes": { "type": "boolean", "description": "El interruptor de la EMPRESA. En `false`, aquí no hay nada que preguntar." }, "orden_despacho": { "type": "string", "enum": [ "fefo", "fifo", "manual" ], "description": "En `manual` no hay sugerencia: elige la persona." }, "id_bodega": { "type": "integer", "nullable": true }, "cantidad": { "type": "number", "nullable": true }, "lotes": { "type": "array", "items": { "type": "object", "properties": { "id_lote": { "type": "integer" }, "codigo": { "type": "string", "description": "El código impreso en la caja." }, "disponible": { "type": "number", "description": "Lo que queda de ese lote, del libro de movimientos." }, "fecha_caducidad": { "type": "string", "nullable": true }, "dias_para_vencer": { "type": "integer", "nullable": true, "description": "Negativo si ya venció. Los vencidos no se listan." }, "fecha_ingreso": { "type": "string", "nullable": true, "description": "Cuándo entró el lote. Es lo que ordena el FIFO." }, "fecha_fabricacion": { "type": "string", "nullable": true }, "registro_sanitario": { "type": "string", "nullable": true }, "tipo": { "type": "integer", "description": "1 lote · 2 serie." } } } }, "sugerencia": { "type": "array", "description": "El reparto propuesto. Se manda tal cual en el campo `lote` de la línea.", "items": { "type": "object", "properties": { "id_lote": { "type": "integer" }, "codigo": { "type": "string" }, "cantidad": { "type": "number" }, "fecha_caducidad": { "type": "string", "nullable": true }, "dias_para_vencer": { "type": "integer", "nullable": true } } } }, "faltante": { "type": "number", "description": "Lo que no alcanzan los lotes. Esa parte sale sin lote asignado." } } } } }, "Listado": { "type": "object", "properties": { "ok": { "type": "boolean" }, "datos": { "type": "object", "properties": { "total": { "type": "integer", "description": "Cuántos hay en total **con los filtros aplicados** —incluida la ventana de 60 días por defecto, si se aplicó—." }, "pagina": { "type": "integer" }, "paginas": { "type": "integer" }, "ventana": { "type": "object", "description": "Solo en los listados de comprobantes. Dice si la lista se limitó a los últimos días por no haber mandado `desde`, `hasta` ni `buscar`.", "properties": { "aplicada": { "type": "boolean" }, "dias": { "type": "integer", "nullable": true, "example": 60 }, "desde": { "type": "string", "nullable": true, "description": "Fecha desde la que se limitó (aaaa-mm-dd)." } } } } } } }, "Archivo": { "type": "object", "properties": { "ok": { "type": "boolean" }, "datos": { "type": "object", "properties": { "nombre": { "type": "string", "description": "Nombre sugerido del fichero." }, "tipo": { "type": "string", "description": "Tipo de contenido: application/pdf o application/xml." }, "contenido": { "type": "string", "format": "byte", "description": "El fichero entero, en base64." } } } } }, "Registro": { "type": "object", "properties": { "ok": { "type": "boolean" }, "datos": { "type": "object", "properties": { "id": { "type": "integer", "description": "Id del registro en AZUR. Guárdelo: es con lo que se le vuelve a referir." }, "ya_existia": { "type": "boolean", "description": "Solo al crear: viene en `true` cuando ya había uno con esa identificación y se devolvió ese en vez de crear otro." } } } } }, "Sesion": { "type": "object", "properties": { "ok": { "type": "boolean" }, "datos": { "type": "object", "properties": { "token": { "type": "string", "description": "Mándelo en `X-Api-Key` en el resto de llamadas. **Se muestra una sola vez**; si se pierde, hay que volver a entrar." }, "caduca_en_dias": { "type": "integer" }, "requiere_2fa": { "type": "boolean", "description": "Si viene en `true` no hay token todavía: falta el segundo factor." }, "id_login": { "type": "string", "description": "Identificador del intento, para mandarlo a /sesion/verificar-2fa." }, "empresa": { "type": "object" }, "ambiente": { "type": "object", "description": "Sobre qué ambiente quedó la sesión. **Mírelo antes de emitir.**" } } } } }, "EntradaLogin": { "type": "object", "required": [ "usuario", "contrasena" ], "properties": { "usuario": { "type": "string", "description": "Nombre de usuario o correo, el mismo con el que entra a la web." }, "contrasena": { "type": "string", "format": "password" }, "dispositivo": { "type": "string", "description": "Cómo llamar a esta sesión en la lista de sesiones: «iPhone de Ana»." } } }, "Entrada2fa": { "type": "object", "required": [ "id_login", "codigo" ], "properties": { "id_login": { "type": "string", "description": "El que devolvió el login." }, "codigo": { "type": "string", "description": "Los seis dígitos de la aplicación de autenticación, o un código de recuperación." } } }, "EntradaBodega": { "type": "object", "description": "Al crear, `nombre` es obligatorio. Al editar, todos los campos son opcionales: lo que no se manda no se toca.", "properties": { "nombre": { "type": "string", "description": "Cómo se llama la bodega. Máximo 300 caracteres." }, "por_defecto": { "type": "boolean", "description": "Marcarla como predeterminada. La que lo estuviera se desmarca sola: solo puede haber una por establecimiento." }, "activa": { "type": "boolean", "description": "Solo al editar. `false` la desactiva, y se rechaza si dentro queda mercadería o si es la predeterminada." } } }, "EntradaCategoria": { "type": "object", "description": "Al crear, `nombre` es obligatorio. Al editar, todos los campos son opcionales: lo que no se manda no se toca.", "properties": { "nombre": { "type": "string", "description": "Cómo se llama la categoría. Máximo 300 caracteres." }, "id_categoriapadre": { "type": "integer", "description": "De qué categoría cuelga. `0` o ausente = raíz. Tiene que ser de la misma cuenta, y no puede cerrar un ciclo." }, "por_defecto": { "type": "boolean", "description": "Marcarla como predeterminada. La que lo estuviera se desmarca sola." }, "activa": { "type": "boolean", "description": "Solo al editar. `false` la desactiva, y se rechaza si tiene productos o categorías hijas activas, o si es la predeterminada." } } }, "EntradaSucursal": { "type": "object", "description": "Al crear, `nombre`, `codigo` y `direccion` son obligatorios — son los mismos tres que exige la pantalla de sucursales del portal. Al editar, todos los campos son opcionales: lo que no se manda no se toca, pero ninguno de esos tres puede quedarse vacío.", "properties": { "nombre": { "type": "string", "description": "Cómo se llama el local: «MATRIZ», «Sucursal Norte». Máximo 300 caracteres." }, "codigo": { "type": "string", "description": "El código del local: «001», «002». Lo pone usted, no se numera solo, y **se puede repetir** — el portal también lo permite —, aunque conviene que no." }, "direccion": { "type": "string", "description": "La que se imprime en el comprobante y viaja al SRI cuando se factura a esta sucursal. Máximo 300 caracteres." }, "telefono": { "type": "string" }, "celular": { "type": "string" }, "correo": { "type": "string", "description": "A donde se manda el comprobante emitido a esta sucursal. Varios, separados por punto y coma." }, "id_provincia": { "type": "integer", "description": "999 es «Sin Especificar», que es lo que trae el formulario de la web." }, "id_ciudad": { "type": "integer", "description": "999 es «Sin Especificar»." }, "por_defecto": { "type": "boolean", "description": "Marcarla como la sucursal a la que se factura cuando no se dice otra. La que lo estuviera se desmarca sola: solo puede haber una. No se puede quitar la marca sin poner otra." }, "activa": { "type": "boolean", "description": "Solo al editar. `false` la da de baja (lo mismo que el DELETE); `true` la recupera. No se puede dar de baja la que está por defecto." } } }, "EntradaCliente": { "type": "object", "required": [ "identificacion", "nombrerazonsocial", "direccion" ], "properties": { "identificacion": { "type": "string", "description": "Cédula, RUC o pasaporte. Se valida: una cédula ecuatoriana mal formada se rechaza aquí, no en el SRI." }, "tipoidentificacion": { "type": "string", "description": "04 RUC · 05 cédula · 06 pasaporte · 07 consumidor final. Si no lo manda, se deduce del número; mándelo si el suyo es un caso raro, como un pasaporte de diez dígitos." }, "nombrerazonsocial": { "type": "string" }, "direccion": { "type": "string", "description": "Obligatoria: va impresa en el comprobante." }, "telefono": { "type": "string" }, "correo": { "type": "string", "description": "A donde se le manda el comprobante. Varios, separados por punto y coma." } } }, "EntradaProveedor": { "type": "object", "required": [ "identificacion", "nombrerazonsocial", "direccion" ], "properties": { "identificacion": { "type": "string" }, "tipoidentificacion": { "type": "string", "description": "04 RUC · 05 cédula · 06 pasaporte. Si no lo manda, se deduce del número." }, "nombrerazonsocial": { "type": "string" }, "direccion": { "type": "string", "description": "Obligatoria." }, "telefono": { "type": "string" }, "correo": { "type": "string" } } }, "EntradaTransportista": { "type": "object", "required": [ "identificacion", "nombrerazonsocial", "direccion" ], "properties": { "identificacion": { "type": "string" }, "tipoidentificacion": { "type": "string", "description": "04 RUC · 05 cédula · 06 pasaporte. Si no lo manda, se deduce del número." }, "nombrerazonsocial": { "type": "string" }, "placa": { "type": "string", "description": "Placa del vehículo. Va impresa en la guía de remisión." }, "licencia": { "type": "string" }, "direccion": { "type": "string" }, "telefono": { "type": "string" }, "correo": { "type": "string" } } }, "EntradaProducto": { "type": "object", "required": [ "codigo", "nombre" ], "properties": { "codigo": { "type": "string", "description": "Código interno. No se puede repetir dentro de la empresa." }, "nombre": { "type": "string", "description": "Lo que sale impreso en el comprobante." }, "precio": { "type": "number", "description": "Precio de venta sin IVA." }, "tipo_iva": { "type": "string", "enum": [ "0", "2", "4", "5", "6", "7", "8", "10" ], "description": "Código del SRI: 0 = 0%, 4 = 15%, 5 = 5%, 6 = no objeto, 7 = exento, 10 = 13%." }, "controla_inventario": { "type": "boolean", "description": "Si lleva existencias. Un servicio va en `false`." }, "costo": { "type": "number" }, "marca": { "type": "string", "description": "Se guarda y se puede buscar por ella." }, "id_categoria": { "type": "integer", "description": "Sale de /producto/categorias." }, "tipo": { "type": "integer", "enum": [ 1, 2 ], "description": "1 bien · 2 servicio. Por defecto 1." }, "codigo_auxiliar": { "type": "string", "description": "Código de barras u otro código con el que también se busca." }, "descripcion": { "type": "string" }, "precio2": { "type": "number" }, "precio3": { "type": "number" }, "precio_por_defecto": { "type": "integer", "enum": [ 1, 2, 3 ], "description": "Cuál de los tres precios se propone al facturar." }, "unidad": { "type": "string", "description": "Id de la unidad de medida. Sale de /catalogos/unidades. 999 es «Sin Especificar»." }, "codigo_ice": { "type": "string", "description": "Código del ICE. Sale de /catalogos/ice. 0 si no lleva." }, "porcentaje_ice": { "type": "number" }, "codigo_irbpnr": { "type": "integer", "description": "**Id** de la fila de IRBPNR, no su código. Sale de /catalogos/irbpnr. 0 si no lleva." }, "id_bodega": { "type": "integer", "description": "Bodega en la que entra el inventario inicial." }, "existencias_iniciales": { "type": "number", "description": "Solo al crear: da de alta el inventario inicial." }, "trazabilidad": { "type": "boolean", "description": "Si se maneja por lotes. **Solo al editar**: al crear, el producto nace sin lotes, igual que en la web." }, "controla_caducidad": { "type": "boolean", "description": "Solo al editar, como `trazabilidad`." }, "facturar_sin_stock": { "type": "boolean", "description": "Si deja facturarlo sin existencias. Solo al crear." }, "stock_minimo": { "type": "number", "description": "Existencia por debajo de la cual el producto sale marcado en /inventario/existencias." }, "stock_maximo": { "type": "number" }, "ubicacion": { "type": "string" }, "subsidio_unitario": { "type": "number", "description": "Solo si el establecimiento tiene habilitado el subsidio; si no, la llamada se rechaza." }, "visible_en_tienda": { "type": "boolean", "description": "Si se publica en la tienda web." }, "fecha_vencimiento": { "type": "string", "description": "aaaa-mm-dd. Si va vacía, se deja la que tuviera." }, "id_cuenta_contable": { "type": "integer", "description": "Cuenta del plan para el bien o servicio. **Necesita el módulo de Contabilidad**; sin él, mandarla es un error. Tiene que existir en el plan de cuentas de la empresa." }, "id_cuenta_inventario": { "type": "integer", "description": "Como `id_cuenta_contable`: cuenta de inventario." }, "id_costodeventa": { "type": "integer", "description": "Como `id_cuenta_contable`: contrapartida de inventario (ingreso)." }, "precio_con_iva": { "type": "boolean", "description": "El `precio` que se manda **ya lleva el IVA dentro** y se guarda la base (se divide por 1,15 y se redondea a 6 decimales), igual que la casilla «Calcular Subtotal sin IVA» del portal.\n\n**Solo al crear** y solo si el establecimiento tiene activado ese cálculo y el producto va con la tarifa por defecto (`tipo_iva` 4). En cualquier otro caso la llamada se rechaza en vez de guardar un precio equivocado. Al editar mande siempre el precio base." }, "precio2_con_iva": { "type": "boolean", "description": "Lo mismo para `precio2`." }, "precio3_con_iva": { "type": "boolean", "description": "Lo mismo para `precio3`." } } }, "EntradaMovimiento": { "type": "object", "required": [ "id_bodega", "productos" ], "properties": { "id_bodega": { "type": "integer", "description": "Bodega sobre la que se mueve. En una transferencia, de la que sale." }, "id_bodega_destino": { "type": "integer", "description": "Solo en transferencias: a dónde llega." }, "fecha": { "type": "string", "description": "aaaa-mm-dd. Por defecto, hoy." }, "concepto": { "type": "string", "description": "Por qué se mueve. Queda en el kardex y en el asiento; escríbalo para quien lo lea dentro de un año." }, "registrar_contabilidad": { "type": "boolean", "default": true, "description": "Ponga `false` solo si el asiento de este movimiento se lleva por otro lado; si no, se queda sin contabilizar." }, "productos": { "type": "array", "items": { "type": "object", "required": [ "id", "cantidad" ], "properties": { "id": { "type": "integer", "description": "Id del producto. Tiene que controlar inventario." }, "cantidad": { "type": "number", "description": "Cuánto se mueve, siempre mayor que cero. **También en un ajuste es la diferencia, no la existencia final**: si el conteo dice 8 y el sistema tiene 10, mande 2 con `tipo: \"disminuir\"`." }, "tipo": { "type": "string", "enum": [ "aumentar", "disminuir" ], "default": "aumentar", "description": "Solo en ajustes: hacia dónde va la corrección. En el resto de movimientos se ignora." }, "costo": { "type": "number", "description": "Costo unitario. En un ingreso vale la pena mandarlo: es lo que valoriza el kardex." }, "lote": { "type": "string" } } } } } }, "EntradaAsiento": { "type": "object", "required": [ "concepto", "lineas" ], "properties": { "fecha": { "type": "string", "description": "aaaa-mm-dd. Por defecto, hoy." }, "concepto": { "type": "string", "description": "De qué es el asiento." }, "lineas": { "type": "array", "description": "Al menos dos. La suma del debe tiene que ser igual a la del haber.", "items": { "type": "object", "required": [ "id_cuenta" ], "properties": { "id_cuenta": { "type": "integer", "description": "Id de la cuenta, de /contabilidad/cuentas. Tiene que ser de movimiento." }, "debe": { "type": "number" }, "haber": { "type": "number", "description": "En cada línea va debe o haber, no los dos." }, "detalle": { "type": "string" }, "id_centrocosto": { "type": "integer", "description": "Opcional, y solo si la cuenta usa centros de costo." } } } } } }, "EntradaWebhook": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "description": "A dónde llamar. Tiene que ser https y estar accesible desde internet." }, "eventos": { "type": "array", "items": { "type": "string" }, "description": "Qué avisar. Si no lo manda, todo." }, "descripcion": { "type": "string" } } }, "SaldoAcreditable": { "type": "object", "properties": { "ok": { "type": "boolean" }, "datos": { "type": "object", "properties": { "en_azur": { "type": "boolean", "description": "false cuando la factura no está en el sistema. Entonces los importes vienen en null." }, "id": { "type": "integer" }, "numero": { "type": "string", "description": "001-001-000000123" }, "fecha": { "type": "string" }, "cliente": { "type": "string" }, "identificacion": { "type": "string" }, "tipo_identificacion": { "type": "string" }, "consumidor_final": { "type": "boolean" }, "anulada": { "type": "boolean" }, "decimales": { "type": [ "integer", "null" ], "description": "Con cuántos decimales se calculó la factura. La nota de crédito debe reproducirla igual." }, "total": { "type": [ "string", "null" ], "description": "Total de la factura, dos decimales." }, "acreditado": { "type": [ "string", "null" ], "description": "Suma de las notas de crédito vivas." }, "saldo": { "type": [ "string", "null" ], "description": "total - acreditado, nunca negativo. Es el tope." }, "tiene_notas": { "type": "boolean" }, "notas": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "numero": { "type": "string" }, "fecha": { "type": "string" }, "valor": { "type": "string" } } } }, "excluida_id_nc": { "type": [ "integer", "null" ] }, "puede_acreditar": { "type": "boolean" }, "motivo": { "type": [ "string", "null" ], "description": "Por qué no se puede, escrito para leérselo a una persona." } } } } }, "LineasAcreditables": { "type": "object", "properties": { "ok": { "type": "boolean" }, "datos": { "type": "object", "properties": { "id": { "type": "integer" }, "numero": { "type": "string", "description": "001-001-000000123" }, "fecha": { "type": "string" }, "cliente": { "type": "string" }, "identificacion": { "type": "string", "description": "El comprador de la factura. La nota de crédito tiene que ir a nombre del mismo." }, "tipo_identificacion": { "type": "string" }, "consumidor_final": { "type": "boolean" }, "anulada": { "type": "boolean" }, "decimales": { "type": [ "integer", "null" ], "description": "Con cuántos decimales se calculó la factura. La nota de crédito debe reproducirla igual." }, "total": { "type": "string" }, "acreditado": { "type": "string", "description": "Suma de las notas de crédito vivas." }, "saldo": { "type": "string", "description": "total - acreditado, nunca negativo. Es el tope en dinero." }, "tiene_notas": { "type": "boolean" }, "notas": { "type": "array", "description": "Las notas de crédito vivas que ya tiene la factura.", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "numero": { "type": "string" }, "fecha": { "type": "string" }, "valor": { "type": "string" }, "estado": { "type": "integer" } } } }, "excluida_id_nc": { "type": [ "integer", "null" ] }, "acreditable": { "type": "boolean", "description": "Si la factura admite hoy una nota de crédito." }, "motivos": { "type": "array", "items": { "type": "string" }, "description": "Por qué no, escrito para leérselo a una persona. Vacío cuando sí." }, "total_lineas": { "type": "integer" }, "lineas_agotadas": { "type": "integer", "description": "Cuántas de esas líneas ya no tienen nada por acreditar." }, "lineas": { "type": "array", "items": { "type": "object", "properties": { "id_linea": { "type": "integer", "description": "Id de la línea en la factura." }, "id_producto": { "type": "integer" }, "id_bodega": { "type": [ "integer", "null" ], "description": "De dónde salió. Es a donde vuelve si se reversa." }, "codigo": { "type": "string" }, "codigo_auxiliar": { "type": [ "string", "null" ] }, "nombre": { "type": "string" }, "detalle": { "type": [ "string", "null" ] }, "cantidad": { "type": "string", "description": "La facturada." }, "acreditada": { "type": "string", "description": "La que ya devolvieron notas de crédito vivas." }, "disponible": { "type": "string", "description": "cantidad - acreditada. El tope de esta línea." }, "agotada": { "type": "boolean", "description": "true cuando `disponible` es 0." }, "preciounitario": { "type": "string", "description": "El de LA FACTURA, no el de la ficha de hoy." }, "descuento": { "type": "string", "description": "El de la línea original. Solo vale si se acredita la cantidad entera; no se prorratea." }, "tipo_iva": { "type": "string" }, "codigo_ice": { "type": [ "integer", "null" ] }, "porcentaje_ice": { "type": [ "string", "null" ] }, "ice_por_unidad": { "type": [ "string", "null" ], "description": "El ICE en dólares por unidad, de la ficha del producto." }, "codigo_irbpnr": { "type": [ "integer", "null" ] }, "unidad": { "type": [ "string", "null" ] }, "unidad_cantidad": { "type": [ "string", "null" ] }, "tipo": { "type": "integer", "description": "1 bien, 2 servicio." }, "ubicacion": { "type": [ "string", "null" ] }, "id_categoria": { "type": [ "integer", "null" ] }, "costo": { "type": [ "string", "null" ], "description": "El costo con el que salió; es el que vuelve al inventario." }, "manejastock": { "type": "boolean", "description": "Si el producto lleva inventario. Si es false, `reversar_producto` no significa nada en esta línea." } } } } } } } }, "Categorias": { "type": "object", "properties": { "ok": { "type": "boolean" }, "datos": { "type": "object", "properties": { "categorias": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "nombre": { "type": "string" }, "id_categoriapadre": { "type": [ "integer", "null" ], "description": "De qué categoría cuelga. `null` si es de primer nivel." }, "por_defecto": { "type": "boolean" }, "productos": { "type": "integer", "description": "Cuántos productos activos tiene." } } } }, "total": { "type": "integer" } } } } }, "CatalogosSri": { "type": "object", "properties": { "ok": { "type": "boolean" }, "datos": { "type": "object", "properties": { "unidades": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Lo que va en `unidad` del producto." }, "nombre": { "type": "string" }, "abreviatura": { "type": "string" }, "cantidad": { "type": "string", "description": "Cuántas unidades base son. La usa el cálculo del IRBPNR." }, "por_defecto": { "type": "boolean", "description": "true en la 999, «Sin Especificar»." } } } }, "ice": { "type": "array", "items": { "type": "object", "properties": { "codigo": { "type": "string", "description": "Lo que va en `codigo_ice` del producto." }, "texto": { "type": "string" } } } }, "irbpnr": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Lo que va en `codigo_irbpnr` del producto. Sí, el id y no el código." }, "codigo": { "type": "string" }, "texto": { "type": "string" } } } } } } } }, "Permisos": { "type": "object", "properties": { "ok": { "type": "boolean" }, "datos": { "type": "object", "properties": { "permisos": { "type": "object", "additionalProperties": { "type": "boolean" }, "description": "Mapa clave => true/false. Ej.: `fac_crear`, `produc_crear`, `fac_descuento`." }, "detalle": { "type": "array", "items": { "type": "object", "properties": { "clave": { "type": "string" }, "nombre": { "type": "string", "description": "El texto en español que ve el dueño en el portal." }, "categoria": { "type": [ "string", "null" ] }, "permitido": { "type": "boolean" } } } }, "total": { "type": "integer" }, "concedidos": { "type": "integer" }, "es_vendedor": { "type": "boolean" }, "vendedor": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "nivel_acceso": { "type": [ "integer", "null" ] } } }, "solo_punto_de_venta": { "type": "boolean" }, "contabilidad": { "type": "boolean", "description": "Si la cuenta tiene el módulo. Si no, los permisos contables no se listan." } } } } }, "Stock": { "type": "object" }, "Contexto": { "type": "object" }, "Plan": { "type": "object" }, "Resumen": { "type": "object" }, "EntradaDocumento": { "type": "object", "required": [ "cliente", "productos" ], "properties": { "cliente": { "type": "object", "properties": { "id_cliente": { "type": "integer", "description": "Id del cliente en AZUR. Es lo más seguro: el resto de datos se toman de su ficha. En compras, liquidaciones y retenciones el campo se llama `id_proveedor`." }, "id_proveedor": { "type": "integer", "description": "Id del proveedor en AZUR: en compras, liquidaciones y retenciones se usa este en lugar de `id_cliente`." }, "id_sucursal": { "type": "integer", "description": "A cuál de sus sucursales se factura. **La dirección impresa en el comprobante y la que viaja al SRI salen de la sucursal**, y el correo al que se envía, también: si el cliente tiene varios locales, esto decide con cuáles datos se emite. Sale de `GET /cliente/{id}/sucursales`.\n\nSolo vale junto al id del cliente o del proveedor, y tiene que ser una sucursal suya y activa; si no lo es, la llamada se rechaza — nunca se cambia por otra en silencio.\n\n**Si no la manda, se usa la marcada por defecto**, que es la misma que el portal trae preseleccionada al facturar. Solo si no hay ninguna marcada se usa la primera de la lista." }, "identificacion": { "type": "string", "description": "Cédula o RUC, si no manda el id." }, "nombrerazonsocial": { "type": "string" }, "tipoidentificacion": { "type": "string", "description": "04 RUC · 05 cédula · 06 pasaporte · 07 consumidor final" }, "direccion": { "type": "string", "description": "Solo si quiere otra distinta de la que tiene guardada la sucursal. **Ojo: se la guarda encima**, porque es ahí donde vive la dirección del cliente. Omítala para emitir con la que ya tiene." } } }, "productos": { "type": "array", "items": { "type": "object", "required": [ "id", "cantidad" ], "properties": { "id": { "type": "integer", "description": "Id del producto en AZUR. Búsquelo con /productos." }, "cantidad": { "type": "number", "description": "Cuántas unidades. Mayor que cero." }, "precio": { "type": "number", "description": "Precio unitario sin IVA. Si no lo manda, se usa el del producto." }, "descuento": { "type": "number", "description": "Descuento en dinero, no en porcentaje." }, "tipo_iva": { "type": "string", "enum": [ "0", "2", "4", "5", "6", "7", "8", "10" ], "description": "Código del SRI: 0 = 0%, 2 = 12%, 4 = 15%, 5 = 5%, 6 = no objeto, 7 = exento, 8 = diferenciado, 10 = 13%. Si no lo manda, el del producto." }, "lote": { "description": "De qué lote sale la línea. Solo si la empresa lleva lotes y el producto los lleva.\n\nTres formas, todas válidas:\n\n· el **código** o el **id** de un lote, y toda la línea sale de ahí: 'L-2409' o 9\n· un **reparto**, que es lo que hace la pantalla web cuando una línea no cabe en un solo lote: [{id_lote: 9, cantidad: 3}, {id_lote: 12, cantidad: 7}]\n· **nada**, y lo elige el sistema por FEFO o FIFO\n\nEl reparto sale ya hecho de 'GET /producto/{id}/lotes?cantidad=X', en su campo `sugerencia`: se puede copiar tal cual.\n\nLos lotes se comprueban contra ese producto: uno de otro producto se rechaza. Si el reparto suma **menos** que la cantidad de la línea, el resto sale sin lote y se avisa; si suma **más**, es un error.", "oneOf": [ { "type": "string" }, { "type": "integer" }, { "type": "array", "items": { "type": "object", "properties": { "id_lote": { "type": "integer", "description": "Id del lote. También vale su código." }, "cantidad": { "type": "number", "description": "Cuántas unidades salen de ese lote." } } } } ] } } } }, "accion": { "type": "string", "enum": [ "guardar", "enviar" ], "default": "guardar", "description": "`guardar` lo deja de borrador; `enviar` lo manda al SRI." }, "fecha": { "type": "string", "description": "aaaa-mm-dd. Por defecto, hoy." }, "formas_pago": { "type": "array", "items": { "type": "object", "properties": { "codigo": { "type": "string", "description": "01 efectivo · 19 tarjeta de crédito · 20 otros" }, "valor": { "type": "number" }, "plazo": { "type": "integer" }, "tiempo": { "type": "string" } } }, "description": "Si no las manda, se pone una de contado por el total." } } }, "EntradaCredito": { "type": "object", "required": [ "cliente", "productos", "sustento" ], "properties": { "cliente": { "type": "object", "properties": { "id_cliente": { "type": "integer", "description": "Id del cliente en AZUR. Es lo más seguro: el resto de datos se toman de su ficha. En compras, liquidaciones y retenciones el campo se llama `id_proveedor`." }, "id_proveedor": { "type": "integer", "description": "Id del proveedor en AZUR: en compras, liquidaciones y retenciones se usa este en lugar de `id_cliente`." }, "id_sucursal": { "type": "integer", "description": "A cuál de sus sucursales se factura. **La dirección impresa en el comprobante y la que viaja al SRI salen de la sucursal**, y el correo al que se envía, también: si el cliente tiene varios locales, esto decide con cuáles datos se emite. Sale de `GET /cliente/{id}/sucursales`.\n\nSolo vale junto al id del cliente o del proveedor, y tiene que ser una sucursal suya y activa; si no lo es, la llamada se rechaza — nunca se cambia por otra en silencio.\n\n**Si no la manda, se usa la marcada por defecto**, que es la misma que el portal trae preseleccionada al facturar. Solo si no hay ninguna marcada se usa la primera de la lista." }, "identificacion": { "type": "string", "description": "Cédula o RUC, si no manda el id." }, "nombrerazonsocial": { "type": "string" }, "tipoidentificacion": { "type": "string", "description": "04 RUC · 05 cédula · 06 pasaporte · 07 consumidor final" }, "direccion": { "type": "string", "description": "Solo si quiere otra distinta de la que tiene guardada la sucursal. **Ojo: se la guarda encima**, porque es ahí donde vive la dirección del cliente. Omítala para emitir con la que ya tiene." } } }, "productos": { "type": "array", "items": { "type": "object", "required": [ "id", "cantidad" ], "properties": { "id": { "type": "integer", "description": "Id del producto en AZUR. Búsquelo con /productos." }, "cantidad": { "type": "number", "description": "Cuántas unidades. Mayor que cero." }, "precio": { "type": "number", "description": "Precio unitario sin IVA. Si no lo manda, se usa el del producto." }, "descuento": { "type": "number", "description": "Descuento en dinero, no en porcentaje." }, "tipo_iva": { "type": "string", "enum": [ "0", "2", "4", "5", "6", "7", "8", "10" ], "description": "Código del SRI: 0 = 0%, 2 = 12%, 4 = 15%, 5 = 5%, 6 = no objeto, 7 = exento, 8 = diferenciado, 10 = 13%. Si no lo manda, el del producto." }, "lote": { "description": "De qué lote sale la línea. Solo si la empresa lleva lotes y el producto los lleva.\n\nTres formas, todas válidas:\n\n· el **código** o el **id** de un lote, y toda la línea sale de ahí: 'L-2409' o 9\n· un **reparto**, que es lo que hace la pantalla web cuando una línea no cabe en un solo lote: [{id_lote: 9, cantidad: 3}, {id_lote: 12, cantidad: 7}]\n· **nada**, y lo elige el sistema por FEFO o FIFO\n\nEl reparto sale ya hecho de 'GET /producto/{id}/lotes?cantidad=X', en su campo `sugerencia`: se puede copiar tal cual.\n\nLos lotes se comprueban contra ese producto: uno de otro producto se rechaza. Si el reparto suma **menos** que la cantidad de la línea, el resto sale sin lote y se avisa; si suma **más**, es un error.", "oneOf": [ { "type": "string" }, { "type": "integer" }, { "type": "array", "items": { "type": "object", "properties": { "id_lote": { "type": "integer", "description": "Id del lote. También vale su código." }, "cantidad": { "type": "number", "description": "Cuántas unidades salen de ese lote." } } } } ] } } } }, "sustento": { "type": "object", "required": [ "secuencial", "motivo" ], "description": "El documento que se modifica. Sin esto no hay nota de crédito.", "properties": { "tipocomprobante": { "type": "string", "default": "01" }, "secuencial": { "type": "string", "example": "001-001-000000123" }, "fecha": { "type": "string" }, "motivo": { "type": "string", "example": "Devolución de mercadería" } } } } }, "EntradaDebito": { "type": "object", "required": [ "cliente", "motivos", "sustento" ], "properties": { "cliente": { "type": "object", "properties": { "id_cliente": { "type": "integer", "description": "Id del cliente en AZUR. Es lo más seguro: el resto de datos se toman de su ficha. En compras, liquidaciones y retenciones el campo se llama `id_proveedor`." }, "id_proveedor": { "type": "integer", "description": "Id del proveedor en AZUR: en compras, liquidaciones y retenciones se usa este en lugar de `id_cliente`." }, "id_sucursal": { "type": "integer", "description": "A cuál de sus sucursales se factura. **La dirección impresa en el comprobante y la que viaja al SRI salen de la sucursal**, y el correo al que se envía, también: si el cliente tiene varios locales, esto decide con cuáles datos se emite. Sale de `GET /cliente/{id}/sucursales`.\n\nSolo vale junto al id del cliente o del proveedor, y tiene que ser una sucursal suya y activa; si no lo es, la llamada se rechaza — nunca se cambia por otra en silencio.\n\n**Si no la manda, se usa la marcada por defecto**, que es la misma que el portal trae preseleccionada al facturar. Solo si no hay ninguna marcada se usa la primera de la lista." }, "identificacion": { "type": "string", "description": "Cédula o RUC, si no manda el id." }, "nombrerazonsocial": { "type": "string" }, "tipoidentificacion": { "type": "string", "description": "04 RUC · 05 cédula · 06 pasaporte · 07 consumidor final" }, "direccion": { "type": "string", "description": "Solo si quiere otra distinta de la que tiene guardada la sucursal. **Ojo: se la guarda encima**, porque es ahí donde vive la dirección del cliente. Omítala para emitir con la que ya tiene." } } }, "motivos": { "type": "array", "description": "Una nota de débito no lleva productos: lleva razones por las que se cobra más.", "items": { "type": "object", "properties": { "razon": { "type": "string", "example": "Interés por mora" }, "valor": { "type": "number" }, "tipo_iva": { "type": "string", "default": "4" } } } }, "sustento": { "type": "object" } } }, "EntradaGuia": { "type": "object", "required": [ "cliente", "productos", "punto_destino", "motivo", "transportista" ], "description": "Una guía dice qué se mueve, de dónde a dónde y cuándo. **No lleva precios ni totales.**", "properties": { "cliente": { "type": "object", "properties": { "id_cliente": { "type": "integer", "description": "Id del cliente en AZUR. Es lo más seguro: el resto de datos se toman de su ficha. En compras, liquidaciones y retenciones el campo se llama `id_proveedor`." }, "id_proveedor": { "type": "integer", "description": "Id del proveedor en AZUR: en compras, liquidaciones y retenciones se usa este en lugar de `id_cliente`." }, "id_sucursal": { "type": "integer", "description": "A cuál de sus sucursales se factura. **La dirección impresa en el comprobante y la que viaja al SRI salen de la sucursal**, y el correo al que se envía, también: si el cliente tiene varios locales, esto decide con cuáles datos se emite. Sale de `GET /cliente/{id}/sucursales`.\n\nSolo vale junto al id del cliente o del proveedor, y tiene que ser una sucursal suya y activa; si no lo es, la llamada se rechaza — nunca se cambia por otra en silencio.\n\n**Si no la manda, se usa la marcada por defecto**, que es la misma que el portal trae preseleccionada al facturar. Solo si no hay ninguna marcada se usa la primera de la lista." }, "identificacion": { "type": "string", "description": "Cédula o RUC, si no manda el id." }, "nombrerazonsocial": { "type": "string" }, "tipoidentificacion": { "type": "string", "description": "04 RUC · 05 cédula · 06 pasaporte · 07 consumidor final" }, "direccion": { "type": "string", "description": "Solo si quiere otra distinta de la que tiene guardada la sucursal. **Ojo: se la guarda encima**, porque es ahí donde vive la dirección del cliente. Omítala para emitir con la que ya tiene." } } }, "productos": { "type": "array", "items": { "type": "object", "required": [ "id", "cantidad" ], "properties": { "id": { "type": "integer", "description": "Id del producto en AZUR. Búsquelo con /productos." }, "cantidad": { "type": "number", "description": "Cuántas unidades. Mayor que cero." }, "precio": { "type": "number", "description": "Precio unitario sin IVA. Si no lo manda, se usa el del producto." }, "descuento": { "type": "number", "description": "Descuento en dinero, no en porcentaje." }, "tipo_iva": { "type": "string", "enum": [ "0", "2", "4", "5", "6", "7", "8", "10" ], "description": "Código del SRI: 0 = 0%, 2 = 12%, 4 = 15%, 5 = 5%, 6 = no objeto, 7 = exento, 8 = diferenciado, 10 = 13%. Si no lo manda, el del producto." }, "lote": { "description": "De qué lote sale la línea. Solo si la empresa lleva lotes y el producto los lleva.\n\nTres formas, todas válidas:\n\n· el **código** o el **id** de un lote, y toda la línea sale de ahí: 'L-2409' o 9\n· un **reparto**, que es lo que hace la pantalla web cuando una línea no cabe en un solo lote: [{id_lote: 9, cantidad: 3}, {id_lote: 12, cantidad: 7}]\n· **nada**, y lo elige el sistema por FEFO o FIFO\n\nEl reparto sale ya hecho de 'GET /producto/{id}/lotes?cantidad=X', en su campo `sugerencia`: se puede copiar tal cual.\n\nLos lotes se comprueban contra ese producto: uno de otro producto se rechaza. Si el reparto suma **menos** que la cantidad de la línea, el resto sale sin lote y se avisa; si suma **más**, es un error.", "oneOf": [ { "type": "string" }, { "type": "integer" }, { "type": "array", "items": { "type": "object", "properties": { "id_lote": { "type": "integer", "description": "Id del lote. También vale su código." }, "cantidad": { "type": "number", "description": "Cuántas unidades salen de ese lote." } } } } ] } } } }, "punto_partida": { "type": "string", "description": "Por defecto, la dirección del establecimiento." }, "punto_destino": { "type": "string" }, "motivo": { "type": "string", "example": "Venta" }, "fecha_inicio": { "type": "string" }, "fecha_fin": { "type": "string" }, "transportista": { "type": "object", "required": [ "identificacion", "razon_social" ], "properties": { "identificacion": { "type": "string" }, "razon_social": { "type": "string" }, "placa": { "type": "string" } } } } }, "EntradaRetencion": { "type": "object", "required": [ "retenciones" ], "description": "**Mande `id_compra` siempre que pueda.** Ese campo es lo único que decide con qué esquema del SRI sale el comprobante: con él sale con el vigente (2.0.0) y queda enlazado con la cuenta por pagar del proveedor; sin él sale con el anterior (1.0.0) y queda suelto. Se sigue admitiendo sin compra para no romper a quien ya emite así, pero la respuesta lo avisa.\n\nCon `id_compra`, el documento de sustento —tipo, número, fecha y autorización— **lo pone el sistema desde la compra**, y el proveedor también: no hace falta mandar ninguno de los dos. La retención sugerida, ya calculada, sale de `GET /compra/{id}/retencion-sugerida`.", "properties": { "id_compra": { "type": "integer", "description": "La compra que se está reteniendo, tal como la devuelve `/compras`. Se comprueba al guardar —que exista, que sea de esta empresa, de este establecimiento y de este ambiente, que tenga sustento tributario, número, fecha y líneas, y que no tenga ya otra retención—, para que el error salga aquí y no cuando el comprobante muera camino del SRI." }, "proveedor": { "type": "object", "properties": { "id_cliente": { "type": "integer", "description": "Id del cliente en AZUR. Es lo más seguro: el resto de datos se toman de su ficha. En compras, liquidaciones y retenciones el campo se llama `id_proveedor`." }, "id_proveedor": { "type": "integer", "description": "Id del proveedor en AZUR: en compras, liquidaciones y retenciones se usa este en lugar de `id_cliente`." }, "id_sucursal": { "type": "integer", "description": "A cuál de sus sucursales se factura. **La dirección impresa en el comprobante y la que viaja al SRI salen de la sucursal**, y el correo al que se envía, también: si el cliente tiene varios locales, esto decide con cuáles datos se emite. Sale de `GET /cliente/{id}/sucursales`.\n\nSolo vale junto al id del cliente o del proveedor, y tiene que ser una sucursal suya y activa; si no lo es, la llamada se rechaza — nunca se cambia por otra en silencio.\n\n**Si no la manda, se usa la marcada por defecto**, que es la misma que el portal trae preseleccionada al facturar. Solo si no hay ninguna marcada se usa la primera de la lista." }, "identificacion": { "type": "string", "description": "Cédula o RUC, si no manda el id." }, "nombrerazonsocial": { "type": "string" }, "tipoidentificacion": { "type": "string", "description": "04 RUC · 05 cédula · 06 pasaporte · 07 consumidor final" }, "direccion": { "type": "string", "description": "Solo si quiere otra distinta de la que tiene guardada la sucursal. **Ojo: se la guarda encima**, porque es ahí donde vive la dirección del cliente. Omítala para emitir con la que ya tiene." } } }, "periodo_fiscal": { "type": "string", "example": "08/2026", "description": "mm/aaaa. Con `id_compra`, por defecto el mes del documento de la compra." }, "retenciones": { "type": "array", "items": { "type": "object", "properties": { "tipo_impuesto": { "type": "string", "enum": [ "1", "2", "6" ], "description": "1 renta · 2 IVA · 6 ISD" }, "codigo": { "type": "string", "description": "Código de retención del SRI." }, "base": { "type": "number" }, "porcentaje": { "type": "number" }, "documento_sustento": { "type": "string", "description": "El documento del proveedor sobre el que se retiene. **Obligatorio solo si no manda `id_compra`**: con compra se toma de ella y lo que se mande aquí no se usa." }, "documento_fecha": { "type": "string" } } } } } }, "RetencionSugerida": { "type": "object", "properties": { "ok": { "type": "boolean" }, "datos": { "type": "object", "properties": { "id_compra": { "type": "integer" }, "compra": { "type": "object", "description": "El documento de sustento tal como saldrá en el comprobante, y su `id_retencion` si ya tiene una." }, "emitible": { "type": "boolean" }, "motivos": { "type": "array", "items": { "type": "string" } }, "retenciones": { "type": "array", "items": { "type": "object" } }, "totales": { "type": "object" }, "propuesta": { "type": "object", "description": "El cuerpo listo para `POST /retencion/guardar`." } } } } }, "EntradaCompra": { "type": "object", "required": [ "proveedor", "productos" ], "description": "Registra una compra. **Todavía no se admiten por API los gastos, los reembolsos ni la retención incrustada**: eso se hace desde el portal.", "properties": { "proveedor": { "type": "object", "properties": { "id_cliente": { "type": "integer", "description": "Id del cliente en AZUR. Es lo más seguro: el resto de datos se toman de su ficha. En compras, liquidaciones y retenciones el campo se llama `id_proveedor`." }, "id_proveedor": { "type": "integer", "description": "Id del proveedor en AZUR: en compras, liquidaciones y retenciones se usa este en lugar de `id_cliente`." }, "id_sucursal": { "type": "integer", "description": "A cuál de sus sucursales se factura. **La dirección impresa en el comprobante y la que viaja al SRI salen de la sucursal**, y el correo al que se envía, también: si el cliente tiene varios locales, esto decide con cuáles datos se emite. Sale de `GET /cliente/{id}/sucursales`.\n\nSolo vale junto al id del cliente o del proveedor, y tiene que ser una sucursal suya y activa; si no lo es, la llamada se rechaza — nunca se cambia por otra en silencio.\n\n**Si no la manda, se usa la marcada por defecto**, que es la misma que el portal trae preseleccionada al facturar. Solo si no hay ninguna marcada se usa la primera de la lista." }, "identificacion": { "type": "string", "description": "Cédula o RUC, si no manda el id." }, "nombrerazonsocial": { "type": "string" }, "tipoidentificacion": { "type": "string", "description": "04 RUC · 05 cédula · 06 pasaporte · 07 consumidor final" }, "direccion": { "type": "string", "description": "Solo si quiere otra distinta de la que tiene guardada la sucursal. **Ojo: se la guarda encima**, porque es ahí donde vive la dirección del cliente. Omítala para emitir con la que ya tiene." } } }, "productos": { "type": "array", "items": { "type": "object", "required": [ "id", "cantidad" ], "properties": { "id": { "type": "integer", "description": "Id del producto en AZUR. Búsquelo con /productos." }, "cantidad": { "type": "number", "description": "Cuántas unidades. Mayor que cero." }, "precio": { "type": "number", "description": "Precio unitario sin IVA. Si no lo manda, se usa el del producto." }, "descuento": { "type": "number", "description": "Descuento en dinero, no en porcentaje." }, "tipo_iva": { "type": "string", "enum": [ "0", "2", "4", "5", "6", "7", "8", "10" ], "description": "Código del SRI: 0 = 0%, 2 = 12%, 4 = 15%, 5 = 5%, 6 = no objeto, 7 = exento, 8 = diferenciado, 10 = 13%. Si no lo manda, el del producto." }, "lote": { "description": "De qué lote sale la línea. Solo si la empresa lleva lotes y el producto los lleva.\n\nTres formas, todas válidas:\n\n· el **código** o el **id** de un lote, y toda la línea sale de ahí: 'L-2409' o 9\n· un **reparto**, que es lo que hace la pantalla web cuando una línea no cabe en un solo lote: [{id_lote: 9, cantidad: 3}, {id_lote: 12, cantidad: 7}]\n· **nada**, y lo elige el sistema por FEFO o FIFO\n\nEl reparto sale ya hecho de 'GET /producto/{id}/lotes?cantidad=X', en su campo `sugerencia`: se puede copiar tal cual.\n\nLos lotes se comprueban contra ese producto: uno de otro producto se rechaza. Si el reparto suma **menos** que la cantidad de la línea, el resto sale sin lote y se avisa; si suma **más**, es un error.", "oneOf": [ { "type": "string" }, { "type": "integer" }, { "type": "array", "items": { "type": "object", "properties": { "id_lote": { "type": "integer", "description": "Id del lote. También vale su código." }, "cantidad": { "type": "number", "description": "Cuántas unidades salen de ese lote." } } } } ] } } } }, "documento": { "type": "object", "description": "El comprobante que dio el proveedor.", "properties": { "numero": { "type": "string", "example": "001-001-000000123" }, "fecha": { "type": "string" }, "autorizacion": { "type": "string" } } }, "sustento": { "type": "string", "default": "01", "description": "Código de sustento tributario del SRI." }, "ingresar_a_inventario": { "type": "boolean" } } } } } }