Utiliser l'API REST

L’API REST de MoneyLights permet à tes propres systèmes de lire et de maintenir les données de ton organisation : transactions, fournisseurs, clients, projets, catégories et flux de trésorerie. Tu t’authentifies avec une clé API.

Appeler l’API

Envoie ta clé dans l’en-tête X-API-Key :

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

Authorization: ApiKey <key> fonctionne aussi. Authorization: Bearer <key> ne fonctionne pas — Bearer appartient à la session du navigateur. Ne mets jamais la clé dans l’URL : de telles requêtes sont refusées avant d’atteindre quoi que ce soit.

La référence lisible par machine

La liste complète et toujours à jour de ce que ta clé peut atteindre est le document OpenAPI public :

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

Il est généré à partir de l’application en cours d’exécution et liste exactement les endpoints publiés, chacun annoté avec la portée qu’il nécessite (x-required-scope). Si ce guide et ce document ne sont jamais d’accord, le document a raison. Tu peux l’utiliser pour un générateur de client ou l’importer dans un outil API.

Ce qui est accessible — et ce qui ne l’est pas

Seuls les endpoints qui ont été explicitement publiés font partie de l’API publique. La règle directrice est enrichir et maintenir, jamais détruire :

Tu peux lister et filtrer les transactions, leur attribuer une catégorie, un fournisseur, un client, un projet ou des allocations de personnes, et créer ou mettre à jour des fournisseurs, des clients, des projets et des catégories.
Tu ne peux pas supprimer un fournisseur, un client, un projet ou une catégorie via l’API. Supprimer un enregistrement auquel d’autres enregistrements font référence est une décision qu’un script ne devrait pas prendre sans surveillance — ces actions se font dans l’application.

Les connexions bancaires, la facturation, la gestion d’équipe et la gestion des clés API ne sont jamais accessibles avec une clé, quelle que soit la portée qu’elle détient.

Limites de taux

Trois limites s’appliquent, et une requête doit satisfaire à toutes :

Plan	Lectures/min par clé	Écritures/min par clé	Requêtes/min par organisation	Par jour, par organisation
Équipe	120	30	120	10 000
Entreprise	600	150	600	100 000

La limite par minute au niveau de l’organisation est celle autour de laquelle concevoir. C’est le même nombre que la limite par clé, donc une clé fonctionnant à plein régime peut consommer toute la minute de l’organisation — ajouter des clés n’achète pas de débit. Si tu exécutes plusieurs intégrations, rythme-les.

Chaque réponse contient X-RateLimit-Limit et X-RateLimit-Remaining. Un 429 contient Retry-After en secondes — respecte-le ; réessayer immédiatement est comment une limite de taux devient une panne.

Erreurs

Les refus portent un code stable sur lequel tu peux te baser. Ceux que tu rencontreras réellement :

Code	Signification
`api_key_invalid`	Malformé, inconnu ou mauvais secret
`api_key_expired`	Passé sa date d’expiration — crée une nouvelle clé
`api_key_revoked`	La clé a été annulée, ou un secret tourné a expiré
`api_key_scope_missing`	La clé manque de la portée dont cet endpoint a besoin
`api_key_endpoint_not_published`	L’endpoint ne fait pas partie de l’API publique
`api_key_rate_limited`	Au-delà d’une limite — respecte `Retry-After`

Une requête sans clé du tout obtient un simple 401 sans code — considère un 401 sans corps comme “J’ai oublié l’en-tête”.

Bon à savoir

Ta clé atteint exactement une organisation — celle pour laquelle elle a été émise. Elle ne peut pas être pointée ailleurs.
Les chiffres d’utilisation sont indicatifs. “Dernière utilisation” et le nombre de requêtes répondent à “est-ce encore utilisé ?”, pas aux questions de facturation.
Privilégie l’API pour les flux de données, et le Serveur MCP lorsque l’appelant est un assistant IA — même identifiant, mêmes portées.