{"openapi":"3.1.0","info":{"title":"ItSave REST API","version":"1.0.0","description":"API financiera de ItSave sobre la misma capa de servicios y límites del MCP."},"servers":[{"url":"https://plataforma.itsave.cl"}],"paths":{"/api/rest/v1/movimientos":{"get":{"operationId":"consultar_movimientos","summary":"Consultar movimientos","description":"Lista los movimientos bancarios CLASIFICADOS de la empresa (ingresos y egresos con su categoría) en un rango de fechas. Úsala para revisar gastos, ventas, proveedores o buscar un pago específico.","tags":["movimientos"],"security":[{"OAuth2":["itsave.lectura"]},{"ApiKey":[]}],"responses":{"200":{"description":"Operación completada"},"400":{"description":"Parámetros inválidos"},"401":{"description":"Credencial ausente o inválida"},"403":{"description":"Permiso insuficiente"},"429":{"description":"Límite de uso o concurrencia alcanzado"}},"parameters":[{"name":"desde","in":"query","required":false,"description":"Fecha inicial AAAA-MM-DD. Por defecto, 30 días antes de 'hasta'.","schema":{"type":"string","format":"date"}},{"name":"hasta","in":"query","required":false,"description":"Fecha final AAAA-MM-DD (inclusive). Por defecto, hoy.","schema":{"type":"string","format":"date"}},{"name":"tipo","in":"query","required":false,"description":"Filtra por tipo.","schema":{"type":"string","enum":["ingreso","egreso"]}},{"name":"categoria","in":"query","required":false,"description":"Filtra por nombre exacto de categoría.","schema":{"type":"string"}},{"name":"texto","in":"query","required":false,"description":"Busca texto en la descripción del movimiento.","schema":{"type":"string"}},{"name":"limite","in":"query","required":false,"description":"Máximo de movimientos a devolver.","schema":{"type":"integer","minimum":1,"maximum":100,"default":100}}]}},"/api/rest/v1/movimientos/sin-clasificar":{"get":{"operationId":"consultar_movimientos_sin_clasificar","summary":"Movimientos sin clasificar","description":"Lista los movimientos que todavía no tienen categoría asignada en ItSave. Úsala para saber qué falta clasificar o para sugerir categorías.","tags":["movimientos"],"security":[{"OAuth2":["itsave.lectura"]},{"ApiKey":[]}],"responses":{"200":{"description":"Operación completada"},"400":{"description":"Parámetros inválidos"},"401":{"description":"Credencial ausente o inválida"},"403":{"description":"Permiso insuficiente"},"429":{"description":"Límite de uso o concurrencia alcanzado"}},"parameters":[{"name":"desde","in":"query","required":false,"description":"Fecha inicial AAAA-MM-DD. Por defecto, 30 días antes de 'hasta'.","schema":{"type":"string","format":"date"}},{"name":"hasta","in":"query","required":false,"description":"Fecha final AAAA-MM-DD (inclusive). Por defecto, hoy.","schema":{"type":"string","format":"date"}},{"name":"limite","in":"query","required":false,"description":"Máximo de movimientos a devolver.","schema":{"type":"integer","minimum":1,"maximum":100,"default":100}}]}},"/api/rest/v1/facturas/venta":{"get":{"operationId":"list_facturas_venta","summary":"Listar facturas de venta","description":"Lista las facturas emitidas por la empresa con cliente, RUT, folio, emisión, vencimiento, neto, IVA, total, monto conciliado, saldo y estado de pago.","tags":["facturas"],"security":[{"OAuth2":["itsave.lectura"]},{"ApiKey":[]}],"responses":{"200":{"description":"Operación completada"},"400":{"description":"Parámetros inválidos"},"401":{"description":"Credencial ausente o inválida"},"403":{"description":"Permiso insuficiente"},"429":{"description":"Límite de uso o concurrencia alcanzado"}},"parameters":[{"name":"desde","in":"query","required":false,"description":"Fecha inicial AAAA-MM-DD. Por defecto, 30 días antes de 'hasta'.","schema":{"type":"string","format":"date"}},{"name":"hasta","in":"query","required":false,"description":"Fecha final AAAA-MM-DD (inclusive). Por defecto, hoy.","schema":{"type":"string","format":"date"}},{"name":"al","in":"query","required":false,"description":"Fecha de referencia AAAA-MM-DD para calcular vencimientos y días de atraso. Por defecto, hoy.","schema":{"type":"string","format":"date"}},{"name":"estado","in":"query","required":false,"description":"Estado de pago calculado con las conciliaciones y la fecha de vencimiento.","schema":{"type":"string","enum":["pagada","pendiente","vencida","parcialmente_pagada"]}},{"name":"texto","in":"query","required":false,"description":"Busca por contraparte, RUT, folio o ID externo.","schema":{"type":"string"}},{"name":"limite","in":"query","required":false,"description":"Máximo de movimientos a devolver.","schema":{"type":"integer","minimum":1,"maximum":100,"default":100}}]}},"/api/rest/v1/facturas/compra":{"get":{"operationId":"list_facturas_compra","summary":"Listar facturas de compra","description":"Lista las facturas recibidas por la empresa con proveedor, RUT, folio, emisión, vencimiento, neto, IVA, total, monto conciliado, saldo y estado de pago.","tags":["facturas"],"security":[{"OAuth2":["itsave.lectura"]},{"ApiKey":[]}],"responses":{"200":{"description":"Operación completada"},"400":{"description":"Parámetros inválidos"},"401":{"description":"Credencial ausente o inválida"},"403":{"description":"Permiso insuficiente"},"429":{"description":"Límite de uso o concurrencia alcanzado"}},"parameters":[{"name":"desde","in":"query","required":false,"description":"Fecha inicial AAAA-MM-DD. Por defecto, 30 días antes de 'hasta'.","schema":{"type":"string","format":"date"}},{"name":"hasta","in":"query","required":false,"description":"Fecha final AAAA-MM-DD (inclusive). Por defecto, hoy.","schema":{"type":"string","format":"date"}},{"name":"al","in":"query","required":false,"description":"Fecha de referencia AAAA-MM-DD para calcular vencimientos y días de atraso. Por defecto, hoy.","schema":{"type":"string","format":"date"}},{"name":"estado","in":"query","required":false,"description":"Estado de pago calculado con las conciliaciones y la fecha de vencimiento.","schema":{"type":"string","enum":["pagada","pendiente","vencida","parcialmente_pagada"]}},{"name":"texto","in":"query","required":false,"description":"Busca por contraparte, RUT, folio o ID externo.","schema":{"type":"string"}},{"name":"limite","in":"query","required":false,"description":"Máximo de movimientos a devolver.","schema":{"type":"integer","minimum":1,"maximum":100,"default":100}}]}},"/api/rest/v1/facturas/detalle":{"get":{"operationId":"get_factura","summary":"Obtener detalle de factura","description":"Devuelve el detalle completo de una factura y los movimientos bancarios o notas de crédito usados para conciliarla. Usa el ID entregado por las herramientas list_facturas.","tags":["facturas"],"security":[{"OAuth2":["itsave.lectura"]},{"ApiKey":[]}],"responses":{"200":{"description":"Operación completada"},"400":{"description":"Parámetros inválidos"},"401":{"description":"Credencial ausente o inválida"},"403":{"description":"Permiso insuficiente"},"429":{"description":"Límite de uso o concurrencia alcanzado"}},"parameters":[{"name":"factura_id","in":"query","required":true,"description":"ID interno de la factura en ItSave.","schema":{"type":"integer"}},{"name":"tipo","in":"query","required":false,"description":"Tipo esperado, para validar la búsqueda.","schema":{"type":"string","enum":["venta","compra"]}},{"name":"al","in":"query","required":false,"description":"Fecha de referencia AAAA-MM-DD para calcular vencimientos y días de atraso. Por defecto, hoy.","schema":{"type":"string","format":"date"}}]}},"/api/rest/v1/cuentas-por-cobrar":{"get":{"operationId":"get_cuentas_por_cobrar","summary":"Cuentas por cobrar","description":"Devuelve facturas de venta con saldo pendiente, vencimientos, días de atraso, totales vencidos y deuda agrupada por cliente.","tags":["cuentas-por-cobrar"],"security":[{"OAuth2":["itsave.lectura"]},{"ApiKey":[]}],"responses":{"200":{"description":"Operación completada"},"400":{"description":"Parámetros inválidos"},"401":{"description":"Credencial ausente o inválida"},"403":{"description":"Permiso insuficiente"},"429":{"description":"Límite de uso o concurrencia alcanzado"}},"parameters":[{"name":"al","in":"query","required":false,"description":"Fecha de referencia AAAA-MM-DD para calcular vencimientos y días de atraso. Por defecto, hoy.","schema":{"type":"string","format":"date"}},{"name":"texto","in":"query","required":false,"description":"Filtra por nombre o RUT del cliente.","schema":{"type":"string"}},{"name":"limite","in":"query","required":false,"description":"Máximo de movimientos a devolver.","schema":{"type":"integer","minimum":1,"maximum":100,"default":100}}]}},"/api/rest/v1/cuentas-por-pagar":{"get":{"operationId":"get_cuentas_por_pagar","summary":"Cuentas por pagar","description":"Devuelve facturas de compra con saldo pendiente, vencimientos, días de atraso, totales vencidos y deuda agrupada por proveedor.","tags":["cuentas-por-pagar"],"security":[{"OAuth2":["itsave.lectura"]},{"ApiKey":[]}],"responses":{"200":{"description":"Operación completada"},"400":{"description":"Parámetros inválidos"},"401":{"description":"Credencial ausente o inválida"},"403":{"description":"Permiso insuficiente"},"429":{"description":"Límite de uso o concurrencia alcanzado"}},"parameters":[{"name":"al","in":"query","required":false,"description":"Fecha de referencia AAAA-MM-DD para calcular vencimientos y días de atraso. Por defecto, hoy.","schema":{"type":"string","format":"date"}},{"name":"texto","in":"query","required":false,"description":"Filtra por nombre o RUT del proveedor.","schema":{"type":"string"}},{"name":"limite","in":"query","required":false,"description":"Máximo de movimientos a devolver.","schema":{"type":"integer","minimum":1,"maximum":100,"default":100}}]}},"/api/rest/v1/cotizaciones/clientes":{"get":{"operationId":"buscar_clientes_cotizacion","summary":"Buscar clientes para cotizar","description":"Busca clientes activos de la empresa por razón social, alias, RUT o correo. Úsala antes de preparar una cotización para resolver el cliente correcto.","tags":["cotizaciones"],"security":[{"OAuth2":["itsave.lectura"]},{"ApiKey":[]}],"responses":{"200":{"description":"Operación completada"},"400":{"description":"Parámetros inválidos"},"401":{"description":"Credencial ausente o inválida"},"403":{"description":"Permiso insuficiente"},"429":{"description":"Límite de uso o concurrencia alcanzado"}},"parameters":[{"name":"texto","in":"query","required":false,"description":"Nombre, RUT, alias o correo a buscar.","schema":{"type":"string"}},{"name":"limite","in":"query","required":false,"description":"","schema":{"type":"integer","minimum":1,"maximum":50,"default":20}}]}},"/api/rest/v1/cotizaciones/productos":{"get":{"operationId":"buscar_productos_cotizacion","summary":"Buscar productos para cotizar","description":"Busca productos y servicios activos del catálogo de la empresa. Devuelve precios netos y brutos para preparar correctamente las líneas de una cotización.","tags":["cotizaciones"],"security":[{"OAuth2":["itsave.lectura"]},{"ApiKey":[]}],"responses":{"200":{"description":"Operación completada"},"400":{"description":"Parámetros inválidos"},"401":{"description":"Credencial ausente o inválida"},"403":{"description":"Permiso insuficiente"},"429":{"description":"Límite de uso o concurrencia alcanzado"}},"parameters":[{"name":"texto","in":"query","required":false,"description":"Nombre, descripción, código o categoría a buscar.","schema":{"type":"string"}},{"name":"limite","in":"query","required":false,"description":"","schema":{"type":"integer","minimum":1,"maximum":50,"default":20}}]}},"/api/rest/v1/cotizaciones/preparar":{"post":{"operationId":"preparar_cotizacion","summary":"Preparar cotización","description":"Valida cliente, líneas, IVA, vigencia y totales sin crear nada. Devuelve un resumen y un token temporal. Muestra mensaje_confirmacion al usuario y espera una confirmación explícita antes de llamar crear_cotizacion. Nunca interpretes la solicitud inicial como confirmación.","tags":["cotizaciones"],"security":[{"OAuth2":["itsave.lectura"]}],"responses":{"200":{"description":"Operación completada"},"400":{"description":"Parámetros inválidos"},"401":{"description":"Credencial ausente o inválida"},"403":{"description":"Permiso insuficiente"},"429":{"description":"Límite de uso o concurrencia alcanzado"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"cliente_id":{"type":"integer","description":"ID devuelto por buscar_clientes_cotizacion."},"lineas":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"object","properties":{"producto_id":{"type":"integer","description":"ID de un producto de ItSave. Si se usa, nombre, descripción y precio pueden omitirse."},"nombre":{"type":"string","description":"Nombre del producto o servicio."},"descripcion":{"type":"string","description":"Detalle opcional de la línea."},"cantidad":{"type":"number","exclusiveMinimum":0,"default":1},"precio_neto":{"type":"number","minimum":0,"description":"Precio unitario neto en CLP, antes de IVA y descuento."},"descuento":{"type":"number","minimum":0,"maximum":100,"default":0}},"additionalProperties":false}},"valida_hasta":{"type":"string","format":"date","description":"Vigencia AAAA-MM-DD. Opcional."},"forma_pago":{"type":"string","description":"Condición de pago, por ejemplo Contado o 30 días."},"notas":{"type":"string","description":"Notas que aparecerán en la cotización."},"tipo_documento":{"type":"string","enum":["33","34"],"description":"33 para cotización afecta a IVA; 34 para cotización exenta."}},"required":["cliente_id","lineas"],"additionalProperties":false}}}}}},"/api/rest/v1/cotizaciones/crear":{"post":{"operationId":"crear_cotizacion","summary":"Crear cotización en borrador","description":"Crea el borrador preparado, pero no lo envía. Llámala únicamente después de que el usuario haya confirmado explícitamente el resumen devuelto por preparar_cotizacion.","tags":["cotizaciones"],"security":[{"OAuth2":["itsave.cotizaciones.crear"]}],"responses":{"200":{"description":"Operación completada"},"400":{"description":"Parámetros inválidos"},"401":{"description":"Credencial ausente o inválida"},"403":{"description":"Permiso insuficiente"},"429":{"description":"Límite de uso o concurrencia alcanzado"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"confirmacion_token":{"type":"string","description":"Token temporal devuelto por preparar_cotizacion tras la confirmación del usuario."}},"required":["confirmacion_token"],"additionalProperties":false}}}}}},"/api/rest/v1/cotizaciones/preparar-envio":{"post":{"operationId":"preparar_envio_cotizacion","summary":"Preparar envío de cotización","description":"Valida la cotización y el correo sin enviar nada. Devuelve el destinatario exacto, una advertencia si difiere del correo del cliente y un token temporal. Muestra mensaje_confirmacion y espera una confirmación explícita antes de llamar enviar_cotizacion.","tags":["cotizaciones"],"security":[{"OAuth2":["itsave.lectura"]}],"responses":{"200":{"description":"Operación completada"},"400":{"description":"Parámetros inválidos"},"401":{"description":"Credencial ausente o inválida"},"403":{"description":"Permiso insuficiente"},"429":{"description":"Límite de uso o concurrencia alcanzado"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"cotizacion_id":{"type":"integer","description":"ID interno de la cotización."},"para":{"type":"string","format":"email","description":"Destinatario exacto."},"mensaje":{"type":"string","description":"Mensaje opcional incluido en el correo."}},"required":["cotizacion_id","para"],"additionalProperties":false}}}}}},"/api/rest/v1/cotizaciones/enviar":{"post":{"operationId":"enviar_cotizacion","summary":"Enviar cotización por correo","description":"Envía el PDF al destinatario confirmado y registra el envío. Llámala únicamente después de una confirmación explícita del usuario para esa cotización y ese correo exactos.","tags":["cotizaciones"],"security":[{"OAuth2":["itsave.cotizaciones.enviar"]}],"responses":{"200":{"description":"Operación completada"},"400":{"description":"Parámetros inválidos"},"401":{"description":"Credencial ausente o inválida"},"403":{"description":"Permiso insuficiente"},"429":{"description":"Límite de uso o concurrencia alcanzado"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"confirmacion_token":{"type":"string","description":"Token temporal devuelto por preparar_envio_cotizacion tras la confirmación."}},"required":["confirmacion_token"],"additionalProperties":false}}}}}}},"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","flows":{"authorizationCode":{"authorizationUrl":"https://plataforma.itsave.cl/oauth/authorize","tokenUrl":"https://plataforma.itsave.cl/oauth/token","scopes":{"itsave.lectura":"Ver movimientos, facturas, clientes, productos y preparar cotizaciones sin guardar cambios.","itsave.cotizaciones.crear":"Crear una cotización como borrador únicamente después de tu confirmación.","itsave.cotizaciones.enviar":"Enviar por correo una cotización únicamente después de confirmar el destinatario."}}}},"ApiKey":{"type":"apiKey","in":"header","name":"X-Api-Key"}}}}