REST API:n käyttö

MoneyLights REST API antaa omien järjestelmiesi lukea ja ylläpitää organisaatiosi tietoja: tapahtumia, toimittajia, asiakkaita, projekteja, kategorioita ja kassavirtaa. Todennat itsesi API-avaimella.

Note

Päätepisteiden polut, scope-merkkijonot ja virhekoodit ovat aina englanniksi — ne ovat koodia, ei käännettävää tekstiä. Alla olevat esimerkit ovat niitä, joita todella lähetät.

API:n kutsuminen

Lähetä avaimesi X-API-Key-otsikossa:

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

Authorization: ApiKey <key> toimii myös. Authorization: Bearer <key> ei toimi — Bearer kuuluu selainistuntoon. Älä koskaan laita avainta URL-osoitteeseen: tällaiset pyynnöt hylätään ennen kuin ne saavuttavat mitään.

Koneellisesti luettava viite

Kattava, aina ajantasainen lista siitä, mitä avaimellasi voi saavuttaa, on julkinen OpenAPI-dokumentti:

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

Se luodaan käynnissä olevasta sovelluksesta ja listaa tarkalleen julkaistut päätepisteet, jokainen merkitty sen vaatimalla scope:lla (x-required-scope). Jos tämä opas ja tuo dokumentti sanovat eri asioita, luota dokumenttiin. Voit syöttää sen asiakasgeneraattorille tai tuoda sen API-työkaluun.

Mitä on saavutettavissa — ja mitä ei

Vain päätepisteet, jotka on nimenomaisesti julkaistu, ovat osa julkista API:a. Ohjeena on rikastaa ja ylläpitää, ei koskaan tuhota:

• Voit listata ja suodattaa tapahtumia, määrittää niille kategorian, toimittajan, asiakkaan tai projektin, jakaa niitä henkilöiden kesken (kohdistukset) ja luoda tai päivittää toimittajia, asiakkaita, projekteja ja kategorioita.
• Et voi poistaa toimittajaa, asiakasta, projektia tai kategoriaa API:n kautta. Tietueen poistaminen, johon muut tietueet viittaavat, on päätös, jota skripti ei saisi tehdä valvomatta — nämä toiminnot kuuluvat sovellukseen.

Pankkiyhteydet, laskutus, tiimin hallinta ja API-avaimen hallinta eivät koskaan ole saavutettavissa avaimella, riippumatta sen sisältämistä scopeista.

Nopeusrajoitukset

Kolme rajoitusta on voimassa, ja pyynnön on täytettävä kaikki:

Suunnitelma	Lukuja/min per avain	Kirjoituksia/min per avain	Pyyntöjä/min per organisaatio	Päivässä, per organisaatio
Team	120	30	120	10 000
Enterprise	600	150	600	100 000

Organisaatiokohtainen minuutin rajoitus on se, jonka mukaan kannattaa suunnitella. Se on sama luku kuin avainkohtainen rajoitus, joten yksi avain, joka toimii täydellä teholla, voi kuluttaa koko organisaation minuutin — avainten lisääminen ei tuo lisää kapasiteettia. Jos sinulla on useita integraatioita, levitä niiden pyyntöjä ajassa.

Jokaisessa vastauksessa on X-RateLimit-Limit ja X-RateLimit-Remaining. 429 sisältää Retry-After sekunteina — kunnioita sitä; välitön uudelleenyritys voi muuttaa lyhyen nopeusrajoituksen katkoksi.

Virheet

Hylkäykset sisältävät vakaan code-arvon, johon integraatiosi voi reagoida. Nämä ovat ne, joita todella kohtaat:

Koodi	Merkitys
api_key_invalid	Avaimen muoto on virheellinen tai se on tuntematon, tai sen salaisuus on väärä
api_key_expired	Vanhenemispäivän jälkeen — luo uusi avain
api_key_revoked	Avain on peruutettu, tai vanhaa salaisuutta käytettiin sen kierrätysikkunan sulkeuduttua
api_key_scope_missing	Avaimelta puuttuu se scope, jota tämä päätepiste tarvitsee
api_key_endpoint_not_published	Päätepiste ei ole osa julkista API:a
api_key_rate_limited	Yli rajan — kunnioita Retry-After

Pyyntö, joka ei lähetä lainkaan avainta, saa yksinkertaisen 401 tyhjällä rungolla ja ilman virhekoodia. Jos näet tämän, avainotsikkoa ei lähetetty.

Päivämääräalueet

GET /api/cashflow/overview ottaa valinnaiset dateFrom ja dateTo. Jos ne jätetään pois, dateFrom on oletuksena kuluvan vuoden 1. tammikuuta ja dateTo tämä päivä (molemmat UTC). Se palauttaa 400:n, ei tyhjää yleiskatsausta, kun:

• päivämäärää ei voida jäsentää (esimerkiksi 2026-13-01);
• dateFrom on myöhempi kuin dateTo;
• lähetetään vain dateTo ja se on aikaisempi kuin oletusalku (kuluvan UTC-vuoden
  1. tammikuuta) — lähetä myös dateFrom;
• lähetetään vain dateFrom ja se on myöhempi kuin tämä päivä — lähetä myös dateTo.

Hyvä tietää

• Avaimesi saavuttaa tarkalleen yhden organisaation — sen, jolle se on myönnetty. Sitä ei voi osoittaa mihinkään muuhun organisaatioon.
• Käyttöluvut ovat likimääräisiä. Käytä “Viimeksi käytetty” ja pyyntömäärää tarkistaaksesi, onko avain edelleen käytössä, ei laskutusta varten.
• Suosi API:a tietovirroissa ja MCP-palvelinta, kun AI-avustaja tekee pyynnöt — sama tunnistus, samat scope:t.