--- name: simpligastos-api description: Usa la API REST de Simpligastos, la plataforma de rendición de gastos para empresas en Chile, para leer y crear gastos (boletas, facturas, kilometraje), rendiciones y su aprobación, fondos por rendir, cajas chicas, pagos, nóminas y personas; marcar lo que el ERP ya contabilizó, sacar asientos contables y verificar webhooks firmados. Úsala cuando el usuario hable de Simpligastos, de rendir gastos o de integrar Simpligastos con un ERP, RR.HH. o un agente. metadata: fuente: "https://app.simpligastos.cl/desarrolladores" version-api: "v1" --- # API de Simpligastos Simpligastos es la plataforma de rendición de gastos para empresas en Chile: cada persona sube la foto de su boleta, se arma una rendición, se aprueba y contabilidad la registra y la paga. Esta API hace por código lo mismo que la app. ## Antes del primer pedido - URL base: `https://app.simpligastos.cl/api/v1`. Todo es JSON (`Content-Type: application/json`), salvo las subidas de archivos (multipart) y las descargas. - La llave va en la variable de entorno `SIMPLIGASTOS_LLAVE`. Si no está, pídele al usuario que la defina; nunca la escribas en el código, en un archivo del repositorio ni en la conversación. - Prueba la llave con `GET /yo`: dice de qué empresa es y con qué roles actúa. ```bash curl "https://app.simpligastos.cl/api/v1/yo" -H "Authorization: Bearer $SIMPLIGASTOS_LLAVE" ``` ## Autenticación - `Authorization: Bearer sg_...` en cada pedido. Las llaves las crea administración en el panel (Integraciones) y se ven una sola vez. - Una llave de lectura solo hace GET; cualquier otro método responde 403. - Cada llave actúa como una persona técnica con roles de contabilidad y administración. No rinde gastos propios ni decide rendiciones. - Con una llave de escritura, `Simpligastos-Persona: ` actúa como esa persona, con sus roles. Hace falta para subir gastos o crear rendiciones a nombre de alguien, y para aprobar o rechazar (una llave sin persona no decide). Los ids salen de `GET /personas`. ## Reglas que no se negocian - **Montos en pesos chilenos enteros.** `total: 15990`, nunca `15990.0`, `"15.990"` ni centavos. - **Fechas sin hora como `AAAA-MM-DD`, en hora de Chile.** Para "hoy", usa la fecha de America/Santiago, no la UTC: `new Date().toISOString().slice(0, 10)` da el día equivocado después de las 21:00. - **Una llave, una empresa.** No hay `empresaId` en los pedidos: la empresa sale de la llave. Para otra empresa hace falta otra llave. - **Lo que no está en la referencia no existe.** No inventes rutas ni campos; si algo falta, dilo. - **Confirma con el usuario antes de lo que no se deshace o mueve plata:** aprobar, rechazar, cerrar rendiciones, pagar o anular pagos y nóminas, cerrar fondos, desactivar personas y borrar datos personales. - Antes de aprobar o rechazar, lee la rendición (`GET /rendiciones/{id}`): sus `observaciones`, `riesgo` y `riesgoMotivos`. ## Estados - Gasto: `leyendo` (la IA lo está leyendo, unos segundos), `listo`, `revisar` (con observaciones), `malo` (hay que repetir la foto). - Rendición: `borrador` → `enviada` → `aprobada` → `cerrada`. Desde enviada puede volver a borrador (quien rinde la retira) o quedar `rechazada` (se corrige y se reenvía). `contabilizadaEn` dice si el ERP ya la registró. - Pago: `pendiente`, `en_nomina`, `pagado`, `anulado`. ## Tareas frecuentes Traer lo aprobado que el ERP no ha registrado y marcarlo al registrarlo: ```bash curl "https://app.simpligastos.cl/api/v1/rendiciones?estado=aprobada&contabilizada=0&limite=100" -H "Authorization: Bearer $SIMPLIGASTOS_LLAVE" curl "https://app.simpligastos.cl/api/v1/rendiciones//asiento" -H "Authorization: Bearer $SIMPLIGASTOS_LLAVE" curl -X POST "https://app.simpligastos.cl/api/v1/rendiciones//contabilizar" -H "Authorization: Bearer $SIMPLIGASTOS_LLAVE" \ -H "Content-Type: application/json" -d '{"referencia":"COMP-2026-00412"}' ``` Subir una boleta a nombre de una persona y esperar la lectura (consulta el gasto hasta que deje de estar `leyendo`): ```bash curl -X POST "https://app.simpligastos.cl/api/v1/gastos" -H "Authorization: Bearer $SIMPLIGASTOS_LLAVE" \ -H "Simpligastos-Persona: " -F "archivo=@boleta.jpg" curl "https://app.simpligastos.cl/api/v1/gastos/" -H "Authorization: Bearer $SIMPLIGASTOS_LLAVE" ``` Aprobar lo que espera a una persona (después de revisarlo y de confirmar con el usuario): ```bash curl "https://app.simpligastos.cl/api/v1/rendiciones?por_aprobar=1" -H "Authorization: Bearer $SIMPLIGASTOS_LLAVE" -H "Simpligastos-Persona: " curl -X POST "https://app.simpligastos.cl/api/v1/rendiciones//aprobar" -H "Authorization: Bearer $SIMPLIGASTOS_LLAVE" \ -H "Simpligastos-Persona: " -H "Content-Type: application/json" -d '{"comentario":"Revisado"}' ``` Mantener las personas al día desde RR.HH.: `POST /personas/sincronizar` con la nómina completa (ver referencia.md). ## Errores comunes Todo error responde `{ "error": "mensaje" }` en español; muéstraselo al usuario tal cual. - 401: falta la llave, fue revocada, o `Simpligastos-Persona` no es una persona activa de la empresa. - 403: llave de lectura en algo que escribe, o la persona no tiene el rol. - 404: el id no existe o es de otra empresa. - 409: una regla del negocio (aprobar la propia rendición, editar algo enviado). No reintentes: el mensaje dice qué falta. - 402: el plan de la empresa no permite subir más (vencido, o XS con sus documentos del mes). - `GET /gastos` vacío con una llave: lista los gastos de quien pregunta; manda `Simpligastos-Persona`. ## Webhooks Si recibes avisos de Simpligastos, verifica `Simpligastos-Firma` (HMAC-SHA256 de `t.cuerpo` con el secreto del webhook, sobre el cuerpo tal como llegó) y usa `Simpligastos-Envio` para no procesar dos veces el mismo aviso. El detalle y el código están en [referencia.md](referencia.md). ## Más - Todos los endpoints con sus parámetros, ejemplos y respuestas: [referencia.md](referencia.md). Léelo antes de usar uno que no aparece arriba. - Si tu entorno conecta servidores MCP, `https://app.simpligastos.cl/api/mcp` ofrece herramientas listas con la misma llave. - Documentación para personas: https://app.simpligastos.cl/desarrolladores