Utilizzo dell'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 da tradurre. 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>

Funziona anche Authorization: ApiKey <key>. 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 ed elenca esattamente gli endpoint pubblicati, ciascuno annotato con l’ambito richiesto (x-required-scope). Se questa guida e quel documento dicono cose diverse, fidati del documento. 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 o un progetto, suddividerle tra le persone (allocazioni) 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 restano 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 essa abbia.

Limiti di frequenza

Si applicano tre limiti e una richiesta deve soddisfare tutti:

Piano	Letture/min per chiave	Scritture/min per chiave	Richieste/min per organizzazione	Per 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 lavora a pieno regime può consumare l’intero minuto dell’organizzazione — aggiungere chiavi non aumenta la capacità. Se hai diverse integrazioni, distribuisci le loro richieste nel tempo.

Ogni risposta porta X-RateLimit-Limit e X-RateLimit-Remaining. Un 429 porta Retry-After in secondi — rispettalo; riprovare immediatamente può trasformare un breve limite di frequenza in un’interruzione.

Errori

I rifiuti portano un code stabile su cui la tua integrazione può agire. Quelli che incontrerai effettivamente:

Codice	Significato
api_key_invalid	La chiave è malformata o sconosciuta, o il suo segreto è errato
api_key_expired	Scaduta — crea una nuova chiave
api_key_revoked	La chiave è stata revocata, o il vecchio segreto è stato utilizzato dopo la chiusura della finestra di rotazione
api_key_scope_missing	Alla chiave manca l’ambito richiesto da 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 che non invia nessuna chiave riceve un semplice 401 con un corpo vuoto e nessun codice di errore. Se vedi questo, l’intestazione della chiave non è stata inviata.

Intervalli di date

GET /api/cashflow/overview accetta un dateFrom e un dateTo opzionali. Se omessi, dateFrom vale per impostazione predefinita il 1° gennaio dell’anno corrente e dateTo la data odierna (entrambi in UTC). Restituisce 400, non una panoramica vuota, quando:

• una data non può essere analizzata (ad esempio 2026-13-01);
• dateFrom è successivo a dateTo;
• viene inviato solo dateTo ed è precedente all’inizio predefinito (1° gennaio dell’anno UTC corrente) — invia anche un dateFrom;
• viene inviato solo dateFrom ed è successivo a oggi — invia anche un dateTo.

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 approssimative. Usa “Ultimo utilizzo” e il conteggio delle richieste per verificare se una chiave è ancora in uso, non per la fatturazione.
• Preferisci l’API per i flussi di dati, e il server MCP quando un assistente AI effettua le richieste — stessa credenziale, stessi ambiti.