REST API kasutamine

MoneyLights REST API võimaldab sinu süsteemidel lugeda ja hallata sinu organisatsiooni andmeid: tehingud, tarnijad, kliendid, projektid, kategooriad ja rahavoog. Autendid end API võtmega.

API kutsumine

Saada oma võti X-API-Key päises:

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

Authorization: ApiKey <key> töötab samuti. Authorization: Bearer <key> ei tööta — Bearer kuulub brauseri sessioonile. Ära pane võtit URL-i: sellised päringud lükatakse tagasi enne, kui need kuhugi jõuavad.

Masinloetav viide

Täielik, alati ajakohane nimekiri sellest, millele sinu võti ligi pääseb, on avalik OpenAPI dokument:

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

See genereeritakse töötava rakenduse põhjal ja loetleb täpselt avaldatud lõpp-punktid, igaühe juures on märgitud vajalik ulatus (x-required-scope). Kui see juhend ja see dokument ütlevad erinevaid asju, usalda dokumenti. Sa võid selle anda kliendi generaatorile või importida API tööriista.

Mis on kätte saadav — ja mis mitte

Ainult need lõpp-punktid, mis on selgelt avaldatud, kuuluvad avalikku API-sse. Juhendav reegel on rikastada ja hallata, mitte hävitada:

Sa võid loetleda ja filtreerida tehinguid, määrata neile kategooria, tarnija, kliendi või projekti, jagada neid inimeste vahel (jaotused) ning luua või uuendada tarnijaid, kliente, projekte ja kategooriaid.
Sa ei saa kustutada tarnijat, klienti, projekti või kategooriat API kaudu. Kirje eemaldamine, millele teised kirjed viitavad, on otsus, mida skript ei tohiks järelevalveta teha — need toimingud kuuluvad rakendusse.

Pangaühendused, arveldamine, meeskonna haldamine ja API võtme haldamine ei ole kunagi kätte saadavad võtmega, olenemata ulatustest, mis tal on.

Kiiruspiirangud

Kolm piirangut kehtivad ja päring peab rahuldama kõik need:

Plaan	Lugemised/min võtme kohta	Kirjutamised/min võtme kohta	Päringud/min organisatsiooni kohta	Päevas, organisatsiooni kohta
Team	120	30	120	10 000
Enterprise	600	150	600	100 000

Organisatsiooni ulatuses kehtiv minutipiirang on see, millega lahenduse kavandamisel arvestada. See on sama number, mis võtme piirang, seega üks võti, mis töötab täisvõimsusel, võib tarbida kogu organisatsiooni minuti — võtmete lisamine ei suurenda läbivoolu. Kui sul on mitu integratsiooni, jaota nende päringud ajas.

Iga vastus sisaldab X-RateLimit-Limit ja X-RateLimit-Remaining. 429 kannab Retry-After sekundites — austa seda; kohe uuesti proovimine võib lühikese kiiruspiirangu muuta katkestuseks.

Vead

Keeldumised kannavad stabiilset code, millele sinu integratsioon saab reageerida. Need, millega sa tegelikult kokku puutud:

Kood	Tähendus
`api_key_invalid`	Võti on vigase vorminguga või tundmatu, või selle saladus on vale
`api_key_expired`	Aegunud — loo uus võti
`api_key_revoked`	Võti on tühistatud või vana saladust on kasutatud pärast selle rotatsiooniakna sulgumist
`api_key_scope_missing`	Võtmel puudub see ulatus, mida see lõpp-punkt vajab
`api_key_endpoint_not_published`	Lõpp-punkt ei kuulu avalikku API-sse
`api_key_rate_limited`	Üle piirangu — austa `Retry-After`

Päring, mis ei saada võtit, saab tavalise 401 tühja kehaga ja ilma veakoodita. Kui sa seda näed, siis võtme päist ei saadetud.

Kuupäeva vahemikud

GET /api/cashflow/overview võtab valikulise dateFrom ja dateTo. Kui need on välja jäetud, on dateFrom vaikimisi käesoleva aasta 1. jaanuar ja dateTo tänane päev (mõlemad UTC). See tagastab 400, mitte tühja ülevaate, kui:

kuupäeva ei saa tõlgendada (näiteks 2026-13-01);
dateFrom on hilisem kui dateTo;
saadetakse ainult dateTo ja see on varasem kui vaikimisi algus (käesoleva UTC-aasta 1. jaanuar) — saada ka dateFrom;
saadetakse ainult dateFrom ja see on hilisem kui tänane päev — saada ka dateTo.

Hea teada

Sinu võti annab ligipääsu täpselt ühele organisatsioonile — sellele, mille jaoks see anti. Seda ei saa suunata kuhugi mujale.
Kasutusnumbrid on ligikaudsed. Kasuta “Viimati kasutatud” ja päringute arvu, et kontrollida, kas võti on endiselt kasutuses, mitte arveldamiseks.
Eelista API-d andmevoogude jaoks ja MCP-serverit siis, kui päringuid teeb AI assistent — sama tunnus, samad ulatused.