Skill para agentes

mkdir -p ~/.claude/skills/simpligastos-api
curl -fsSL https://simpligastos.cl/desarrolladores/skill/SKILL.md -o ~/.claude/skills/simpligastos-api/SKILL.md
curl -fsSL https://simpligastos.cl/desarrolladores/skill/referencia.md -o ~/.claude/skills/simpligastos-api/referencia.md

mkdir -p .claude/skills/simpligastos-api
curl -fsSL https://simpligastos.cl/desarrolladores/skill/SKILL.md -o .claude/skills/simpligastos-api/SKILL.md
curl -fsSL https://simpligastos.cl/desarrolladores/skill/referencia.md -o .claude/skills/simpligastos-api/referencia.md

---
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://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://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://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: <id de 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://simpligastos.cl/api/v1/rendiciones?estado=aprobada&contabilizada=0&limite=100" -H "Authorization: Bearer $SIMPLIGASTOS_LLAVE"
curl "https://simpligastos.cl/api/v1/rendiciones/<id>/asiento" -H "Authorization: Bearer $SIMPLIGASTOS_LLAVE"
curl -X POST "https://simpligastos.cl/api/v1/rendiciones/<id>/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://simpligastos.cl/api/v1/gastos" -H "Authorization: Bearer $SIMPLIGASTOS_LLAVE" \
  -H "Simpligastos-Persona: <id de persona>" -F "archivo=@boleta.jpg"
curl "https://simpligastos.cl/api/v1/gastos/<id del gasto>" -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://simpligastos.cl/api/v1/rendiciones?por_aprobar=1" -H "Authorization: Bearer $SIMPLIGASTOS_LLAVE" -H "Simpligastos-Persona: <id>"
curl -X POST "https://simpligastos.cl/api/v1/rendiciones/<id>/aprobar" -H "Authorization: Bearer $SIMPLIGASTOS_LLAVE" \
  -H "Simpligastos-Persona: <id>" -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://simpligastos.cl/api/mcp` ofrece herramientas listas con la misma llave.
- Documentación para personas: https://simpligastos.cl/desarrolladores