REST API:n käyttäminen

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

Note

Päätepisteiden polut, scope-merkkijonot ja virhekoodit ovat aina englanniksi — ne ovat koodia, eivät kopioita. Alla olevat esimerkit ovat sitä, mitä 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

Täydellinen, 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 tarvitsemallaan scope:lla (x-required-scope). Jos tämä opas ja tuo dokumentti koskaan ovat eri mieltä, dokumentti on oikeassa. Voit syöttää sen asiakassukupolvelle 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, projektin tai henkilön allokointeja, 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 skriptin ei tulisi tehdä valvomatta — nämä toimet kuuluvat sovellukseen.

Pankkiyhteydet, laskutus, tiimin hallinta ja API-avainten hallinta eivät koskaan ole saavutettavissa avaimella, riippumatta sen 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
Tiimi	120	30	120	10 000
Yritys	600	150	600	100 000

Organisaatiokohtainen minuutin rajoitus on se, jonka ympärille 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 käytät useita integraatioita, säätele niiden tahtia.

Jokaisessa vastauksessa on X-RateLimit-Limit ja X-RateLimit-Remaining. 429-koodi sisältää Retry-After sekunteina — kunnioita sitä; välitön uudelleenyritys on tapa, jolla nopeusrajoitus muuttuu katkoksi.

Virheet

Hylkäykset sisältävät vakaan code, johon voit reagoida. Nämä ovat niitä, joihin todella törmäät:

Koodi	Merkitys
api_key_invalid	Virheellinen, tuntematon tai väärä salaisuus
api_key_expired	Vanhenemispäivän jälkeen — luo uusi avain
api_key_revoked	Avainta on leikattu tai kierrätetty salaisuus on vanhentunut
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ö, jossa ei ole avainta lainkaan, saa pelkän 401 ilman koodia — käsittele ilman sisältöä olevaa 401:stä “Unohdin otsikon”.

Hyvä tietää

• Avaimesi saavuttaa tarkalleen yhden organisaation — sen, jolle se on myönnetty. Sitä ei voi osoittaa mihinkään muuhun.
• Käyttöluvut ovat suuntaa-antavia. “Viimeksi käytetty” ja pyyntöjen määrä vastaavat kysymykseen “onko tämä vielä käytössä?”, eivät laskutuskysymyksiin.
• Suosi API:a tietovirroissa ja MCP Server kun kutsuja on AI-avustaja — sama tunnistus, samat scope:t.