{ "openapi": "3.0.0", "info": { "title": "Rendiciones API", "description": "API pública para integrar Rendiciones con ERP y otros sistemas. Autenticación con una llave de API (Configuración → API e integraciones) en el header `Authorization: Bearer rk_live_…`. Límite: 120 peticiones por minuto por llave. Montos como texto decimal; fechas en ISO 8601.", "version": "1.0" }, "servers": [ { "url": "https://rendiciones.comcait.com" } ], "tags": [ { "name": "Rendiciones API v1" } ], "paths": { "/api/v1/expenses": { "get": { "tags": [ "Rendiciones API v1" ], "summary": "Lista gastos", "description": "Ordenados del más reciente al más antiguo. Permiso: `expenses:read`.", "security": [ { "apiKey": [] } ], "operationId": "getexpenses", "parameters": [ { "name": "cursor", "in": "query", "required": false, "description": "Cursor devuelto como `nextCursor` en la página anterior.", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "description": "Entre 1 y 200. Por defecto 50.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "from", "in": "query", "required": false, "description": "Fecha del gasto desde (incluida).", "schema": { "type": "string", "example": "2026-09-01" } }, { "name": "to", "in": "query", "required": false, "description": "Fecha del gasto hasta (incluida).", "schema": { "type": "string", "example": "2026-09-30" } }, { "name": "status", "in": "query", "required": false, "description": "Estado de la rendición del gasto, o `unreported` si no está en ninguna.", "schema": { "type": "string", "enum": [ "unreported", "DRAFT", "SUBMITTED", "RETURNED", "APPROVED", "REJECTED", "PAID" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExpensePage" } } } }, "400": { "description": "Parámetros inválidos", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Llave inválida, revocada o vencida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso expenses:read", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe en tu empresa", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Demasiadas peticiones con esta llave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/reports": { "get": { "tags": [ "Rendiciones API v1" ], "summary": "Lista rendiciones", "description": "Ordenadas por última actualización. Permiso: `reports:read`.", "security": [ { "apiKey": [] } ], "operationId": "getreports", "parameters": [ { "name": "cursor", "in": "query", "required": false, "description": "Cursor devuelto como `nextCursor` en la página anterior.", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "description": "Entre 1 y 200. Por defecto 50.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "DRAFT", "SUBMITTED", "RETURNED", "APPROVED", "REJECTED", "PAID" ] } }, { "name": "updatedFrom", "in": "query", "required": false, "description": "Actualizadas desde esta fecha.", "schema": { "type": "string", "example": "2026-09-01" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportPage" } } } }, "400": { "description": "Parámetros inválidos", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Llave inválida, revocada o vencida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso reports:read", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe en tu empresa", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Demasiadas peticiones con esta llave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/reports/{id}": { "get": { "tags": [ "Rendiciones API v1" ], "summary": "Detalle de una rendición con sus gastos", "description": "Permiso: `reports:read`.", "security": [ { "apiKey": [] } ], "operationId": "getreports_id", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportDetailOut" } } } }, "400": { "description": "Parámetros inválidos", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Llave inválida, revocada o vencida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso reports:read", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe en tu empresa", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Demasiadas peticiones con esta llave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/reports/{id}/mark-exported": { "post": { "tags": [ "Rendiciones API v1" ], "summary": "Marca una rendición como importada por el ERP", "description": "Queda en el historial de la rendición y en la bitácora. Permiso: `reports:write`.", "security": [ { "apiKey": [] } ], "operationId": "postreports_id_mark_exported", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportedOut" } } } }, "400": { "description": "Parámetros inválidos", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Llave inválida, revocada o vencida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso reports:write", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe en tu empresa", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Demasiadas peticiones con esta llave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarkExportedDto" } } } } } }, "/api/v1/users": { "get": { "tags": [ "Rendiciones API v1" ], "summary": "Lista personas", "description": "Sin datos bancarios ni de seguridad. Permiso: `users:read`.", "security": [ { "apiKey": [] } ], "operationId": "getusers", "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/UserOut" } } } } }, "400": { "description": "Parámetros inválidos", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Llave inválida, revocada o vencida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso users:read", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe en tu empresa", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Demasiadas peticiones con esta llave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/catalog": { "get": { "tags": [ "Rendiciones API v1" ], "summary": "Categorías (con cuenta contable), centros de costo y monedas", "description": "Permiso: `catalog:read`.", "security": [ { "apiKey": [] } ], "operationId": "getcatalog", "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogOut" } } } }, "400": { "description": "Parámetros inválidos", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Llave inválida, revocada o vencida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso catalog:read", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe en tu empresa", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Demasiadas peticiones con esta llave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "rk_live_…", "description": "Llave de API" } }, "schemas": { "ExpenseOut": { "type": "object", "required": [ "id", "date", "userId", "kind", "merchant", "documentType", "currency", "amount", "amountBase", "reimbursable", "rejected", "createdAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "date": { "type": "string", "example": "2026-09-15" }, "userId": { "type": "string", "format": "uuid" }, "reportId": { "type": "string", "nullable": true, "format": "uuid" }, "reportNumber": { "type": "integer", "nullable": true, "example": 12 }, "reportStatus": { "type": "string", "nullable": true, "enum": [ "DRAFT", "SUBMITTED", "RETURNED", "APPROVED", "REJECTED", "PAID" ] }, "kind": { "type": "string", "enum": [ "REGULAR", "MILEAGE", "PER_DIEM" ] }, "merchant": { "type": "string" }, "merchantRut": { "type": "string", "nullable": true, "example": "76.086.428-5" }, "documentType": { "type": "string", "example": "FACTURA" }, "documentNumber": { "type": "string", "nullable": true }, "currency": { "type": "string", "example": "CLP" }, "amount": { "type": "string", "example": "42000.00", "description": "Monto en la moneda original (decimal como texto)." }, "amountBase": { "type": "string", "example": "42000.00", "description": "Monto en la moneda base de la empresa." }, "netAmount": { "type": "string", "nullable": true, "example": "35294.00" }, "taxAmount": { "type": "string", "nullable": true, "example": "6706.00" }, "reimbursable": { "type": "boolean" }, "categoryId": { "type": "string", "nullable": true, "format": "uuid" }, "glAccount": { "type": "string", "nullable": true, "example": "5101-03" }, "costCenterCode": { "type": "string", "nullable": true, "example": "COM" }, "rejected": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" } } }, "ExpensePage": { "type": "object", "required": [ "data", "nextCursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ExpenseOut" } }, "nextCursor": { "type": "string", "nullable": true } } }, "ReportOut": { "type": "object", "required": [ "id", "number", "title", "status", "userId", "total", "updatedAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "integer", "example": 12 }, "title": { "type": "string" }, "status": { "type": "string", "enum": [ "DRAFT", "SUBMITTED", "RETURNED", "APPROVED", "REJECTED", "PAID" ] }, "userId": { "type": "string", "format": "uuid" }, "total": { "type": "string", "example": "185500.00" }, "approvedTotal": { "type": "string", "nullable": true }, "submittedAt": { "type": "string", "nullable": true, "format": "date-time" }, "approvedAt": { "type": "string", "nullable": true, "format": "date-time" }, "paidAt": { "type": "string", "nullable": true, "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "ReportDetailOut": { "allOf": [ { "$ref": "#/components/schemas/ReportOut" }, { "type": "object", "properties": { "expenses": { "type": "array", "items": { "$ref": "#/components/schemas/ExpenseOut" } } } } ] }, "ReportPage": { "type": "object", "required": [ "data", "nextCursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ReportOut" } }, "nextCursor": { "type": "string", "nullable": true } } }, "UserOut": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "email": { "type": "string" }, "name": { "type": "string" }, "rut": { "type": "string", "nullable": true }, "position": { "type": "string", "nullable": true }, "role": { "type": "string", "enum": [ "ADMIN", "FINANCE", "APPROVER", "EMPLOYEE" ] }, "active": { "type": "boolean" }, "managerId": { "type": "string", "nullable": true, "format": "uuid" }, "costCenterCode": { "type": "string", "nullable": true } } }, "CatalogOut": { "type": "object", "properties": { "categories": { "type": "array", "items": { "type": "object" }, "example": [ { "id": "uuid", "name": "Alimentación", "glAccount": "5101-01", "active": true } ] }, "costCenters": { "type": "array", "items": { "type": "object" }, "example": [ { "id": "uuid", "code": "COM", "name": "Comercial", "active": true } ] }, "currencies": { "type": "array", "items": { "type": "object" }, "example": [ { "code": "USD", "name": "Dólar estadounidense", "rate": "948.500000", "active": true } ] } } }, "MarkExportedDto": { "type": "object", "properties": { "reference": { "type": "string", "maxLength": 120, "example": "COMP-2026-00123", "description": "Identificador del comprobante en el ERP." } } }, "ExportedOut": { "type": "object", "properties": { "ok": { "type": "boolean" }, "reportId": { "type": "string", "format": "uuid" } } }, "Error": { "type": "object", "properties": { "message": { "type": "string" } } } } } }