Usar la API REST

La API REST de MoneyLights permite que tus propios sistemas lean y mantengan los datos de tu organización: transacciones, proveedores, clientes, proyectos, categorías y flujo de efectivo. Te autenticas con una clave API.

Llamar a la API

Envía tu clave en el encabezado X-API-Key:

GET /api/transactions HTTP/1.1
Host: api.moneylights.app
X-API-Key: ml_sk_<key-id>_<secret>

Authorization: ApiKey <key> también funciona. Authorization: Bearer <key> no funciona — Bearer pertenece a la sesión del navegador. Nunca pongas la clave en la URL: esas solicitudes se rechazan antes de llegar a ningún sitio.

La referencia legible por máquina

La lista completa y siempre actualizada de lo que tu clave puede alcanzar es el documento público OpenAPI:

GET https://api.moneylights.app/api/public/openapi.json

Se genera a partir de la aplicación en ejecución y lista exactamente los endpoints publicados, cada uno anotado con el alcance que requiere (x-required-scope). Si esta guía y ese documento dicen cosas diferentes, confía en el documento. Puedes usarlo con un generador de clientes o importarlo en una herramienta API.

Lo que es alcanzable — y lo que no

Solo los endpoints que fueron explícitamente publicados son parte de la API pública. La regla guía es enriquecer y mantener, nunca destruir:

Puedes listar y filtrar transacciones, asignarles una categoría, proveedor, cliente o proyecto, dividirlas entre personas (asignaciones), y crear o actualizar proveedores, clientes, proyectos y categorías.
No puedes eliminar un proveedor, cliente, proyecto o categoría a través de la API. Eliminar un registro al que apuntan otros registros es una decisión que un script no debe tomar sin supervisión — esas acciones se quedan en la aplicación.

Las conexiones bancarias, la facturación, la gestión de equipos y la gestión de claves API nunca son alcanzables con una clave, sean cuales sean los alcances que tenga.

Límites de tasa

Se aplican tres límites, y una solicitud debe satisfacer todos ellos:

Plan	Lecturas/min por clave	Escrituras/min por clave	Solicitudes/min por organización	Por día, por organización
Team	120	30	120	10 000
Enterprise	600	150	600	100 000

El límite por minuto a nivel de organización es el que debes tener en cuenta al diseñar. Es el mismo número que el límite por clave, así que una clave funcionando al máximo puede consumir todo el minuto de la organización — añadir claves no aumenta el rendimiento. Si tienes varias integraciones, distribuye sus solicitudes a lo largo del tiempo.

Cada respuesta lleva X-RateLimit-Limit y X-RateLimit-Remaining. Un 429 lleva Retry-After en segundos — respétalo; reintentar de inmediato puede convertir un límite de tasa corto en una interrupción.

Errores

Los rechazos llevan un code estable según el cual tu integración puede actuar. Los que realmente encontrarás:

Código	Significado
`api_key_invalid`	La clave está mal formada o es desconocida, o su secreto es incorrecto
`api_key_expired`	Pasada su fecha de caducidad — crea una nueva clave
`api_key_revoked`	La clave fue revocada, o se usó el antiguo secreto después de que se cerró su ventana de rotación
`api_key_scope_missing`	La clave carece del alcance que necesita este endpoint
`api_key_endpoint_not_published`	El endpoint no es parte de la API pública
`api_key_rate_limited`	Por encima de un límite — respeta `Retry-After`

Una solicitud que no envía ninguna clave recibe un simple 401 con un cuerpo vacío y sin código de error. Si ves eso, el encabezado de la clave no fue enviado.

Rangos de fechas

GET /api/cashflow/overview toma un dateFrom y dateTo opcionales. Si se omiten, dateFrom se establece por defecto en el 1 de enero del año actual y dateTo en hoy (ambos en UTC). Devuelve 400, no un resumen vacío, cuando:

una fecha no puede ser analizada (por ejemplo 2026-13-01);
dateFrom es posterior a dateTo;
solo se envía dateTo y es anterior al inicio predeterminado (1 de enero del año UTC actual) — envía también un dateFrom;
solo se envía dateFrom y es posterior a hoy — envía también un dateTo.

Es bueno saber

Tu clave alcanza exactamente una organización — aquella para la que se emitió. No se puede dirigir a ninguna otra.
Las cifras de uso son aproximadas. Usa “Último uso” y el conteo de solicitudes para verificar si una clave sigue en uso, no para facturación.
Prefiere la API para flujos de datos, y el servidor MCP cuando un asistente de IA realiza las solicitudes — misma credencial, mismos alcances.