Usando 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.

Llamando 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: tales solicitudes son rechazadas antes de llegar a cualquier cosa.

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 alguna vez discrepan, el documento es correcto. Puedes alimentarlo a un generador de clientes o importarlo en una herramienta API.

Lo que es accesible — 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, proyecto o asignaciones de persona, 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 debería tomar sin supervisión — esas acciones viven en la aplicación.

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

Límites de tasa

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

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

El límite por minuto a nivel de organización es el que debes considerar. 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 — agregar claves no aumenta el rendimiento. Si tienes varias integraciones, pónlas a un ritmo adecuado.

Cada respuesta lleva X-RateLimit-Limit y X-RateLimit-Remaining. Un 429 lleva Retry-After en segundos — respétalo; intentar de inmediato es cómo un límite de tasa se convierte en una interrupción.

Errores

Las negativas llevan un code estable en el que puedes basarte. Los que realmente encontrarás:

Código	Significado
`api_key_invalid`	Malformado, desconocido o secreto incorrecto
`api_key_expired`	Pasado su fecha de caducidad — crea una nueva clave
`api_key_revoked`	La clave fue cancelada, o un secreto rotado expiró
`api_key_scope_missing`	La clave carece del alcance que este endpoint necesita
`api_key_endpoint_not_published`	El endpoint no es parte de la API pública
`api_key_rate_limited`	Más allá de un límite — respeta `Retry-After`

Una solicitud sin clave en absoluto recibe un simple 401 sin código — trata un 401 sin cuerpo como “Olvidé el encabezado”.

Bueno saber

Tu clave alcanza exactamente una organización — la que se emitió para. No puede ser apuntada a ningún otro lugar.
Las cifras de uso son indicativas. “Último uso” y el conteo de solicitudes responden “¿esto sigue en uso?”, no preguntas de facturación.
Prefiere la API para flujos de datos, y el Servidor MCP cuando el llamador es un asistente de IA — misma credencial, mismos alcances.