Utilizzare l'API REST

L’API REST di MoneyLights consente ai tuoi sistemi di leggere e gestire i dati della tua organizzazione: transazioni, fornitori, clienti, progetti, categorie e flusso di cassa. Ti autentichi con una chiave API.

Nota

I percorsi degli endpoint, le stringhe di ambito e i codici di errore sono sempre in inglese — sono codice, non testo. Gli esempi qui sotto sono ciò che invierai effettivamente.

Chiamare l’API

Invia la tua chiave nell’intestazione X-API-Key:

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

Authorization: ApiKey <key> funziona anche. Authorization: Bearer <key> non funziona — Bearer appartiene alla sessione del browser. Non mettere mai la chiave nell’URL: tali richieste vengono rifiutate prima di raggiungere qualsiasi cosa.

Il riferimento leggibile dalla macchina

L’elenco completo e sempre aggiornato di ciò che la tua chiave può raggiungere è il documento OpenAPI pubblico:

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

Viene generato dall’applicazione in esecuzione e elenca esattamente gli endpoint pubblicati, ciascuno annotato con l’ambito richiesto (x-required-scope). Se questa guida e quel documento mai discordano, il documento è corretto. Puoi fornirlo a un generatore di client o importarlo in uno strumento API.

Cosa è raggiungibile — e cosa non lo è

Solo gli endpoint che sono stati esplicitamente pubblicati fanno parte dell’API pubblica. La regola guida è arricchire e mantenere, mai distruggere:

• Puoi elencare e filtrare le transazioni, assegnare loro una categoria, un fornitore, un cliente, un progetto o allocazioni di persone, e creare o aggiornare fornitori, clienti, progetti e categorie.
• Non puoi eliminare un fornitore, un cliente, un progetto o una categoria tramite l’API. Rimuovere un record a cui altri record fanno riferimento è una decisione che uno script non dovrebbe prendere senza supervisione — quelle azioni vivono nell’app.

Le connessioni bancarie, la fatturazione, la gestione del team e la gestione delle chiavi API non sono mai raggiungibili con una chiave, qualunque ambito possieda.

Limiti di utilizzo

Si applicano tre limiti, e una richiesta deve soddisfarli tutti:

Piano	Letture/min per chiave	Scritture/min per chiave	Richieste/min per organizzazione	Al giorno, per organizzazione
Team	120	30	120	10 000
Enterprise	600	150	600	100 000

Il limite per minuto a livello di organizzazione è quello su cui progettare. È lo stesso numero del limite per chiave, quindi una chiave che funziona a pieno regime può consumare l’intero minuto dell’organizzazione — aggiungere chiavi non aumenta la capacità. Se esegui diverse integrazioni, dosale.

Ogni risposta porta X-RateLimit-Limit e X-RateLimit-Remaining. Un 429 porta Retry-After in secondi — rispettalo; riprovare immediatamente è come un limite di utilizzo diventa un’interruzione.

Errori

I rifiuti portano un code stabile su cui puoi attivarti. Quelli che incontrerai effettivamente:

Codice	Significato
api_key_invalid	Malformata, sconosciuta o chiave segreta errata
api_key_expired	Scaduta — crea una nuova chiave
api_key_revoked	La chiave è stata annullata, o una chiave segreta ruotata è scaduta
api_key_scope_missing	La chiave manca dell’ambito necessario a questo endpoint
api_key_endpoint_not_published	L’endpoint non fa parte dell’API pubblica
api_key_rate_limited	Oltre un limite — rispetta Retry-After

Una richiesta senza chiave ottiene un semplice 401 senza codice — tratta un 401 senza corpo come “Ho dimenticato l’intestazione”.

Buono a sapersi

• La tua chiave raggiunge esattamente un’organizzazione — quella per cui è stata emessa. Non può essere indirizzata altrove.
• Le cifre di utilizzo sono indicative. “Ultimo utilizzo” e il conteggio delle richieste rispondono a “è ancora in uso?”, non a domande di fatturazione.
• Preferisci l’API per i flussi di dati, e il MCP Server quando il chiamante è un assistente AI — stessa credenziale, stessi ambiti.