E-arveldaja liidestamine: API võimalused, hind ja piirangud

Mis on e-arveldaja ja kus ta päriselt asub

e-arveldaja ei ole eraldi veebileht, vaid moodul e-äriregistri portaalis. See tähendab, et sisselogimine käib ID-kaardi, Smart-ID või Mobiil-ID-ga samamoodi nagu registriavalduste puhul, ja ettevõtte andmed tulevad registrist, mitte käsitsi sisestatuna.

Tarkvara koosneb viiest moodulist: arveldamine, raamatupidamine, aruandlus, personal ja seadistused. Keskkond töötab eesti ja inglise keeles. RIKi sõnul kasutab seda üle 30 tuhande kasutaja.

Liidestamise mõttes tähendab see, et küsimus on andmevoos, mitte moodulis, ja sellepärast kuulub e-arveldaja liidestamine pigem tarkvaraarenduse kui raamatupidamistarkvara valikusse.

Üks piirang tuleb kohe ära öelda, sest see mõjutab liidestamise mõttekust: laomoodulit ei ole. RIKi juhend ütleb, et laoarvestuse kanded, näiteks müüdud kauba kulu ja inventuur, tuleb teha käsitsi pearaamatusse. Kui sinu äri põhineb laoseisul, ei ole e-arveldaja integratsiooni alus ja ükski API ei tee sellest paremat tarkvara.

Hind: esimene aasta tasuta, edasi alates 5 eurost

Tavapärane raamatupidamiskasutus on tasuta esimesel aastal, kuid avalikule sektorile e-arvete koostamisel ja saatmisel kehtib tähtajatu tasuta erand. See on piisavalt oluline erinevus, et seda enne arhitektuuriotsust kontrollida, sest „tasuta raamatupidamine“ on argument, millega mitmed projektid algavad.

Avaliku sektori erand on sisuline, mitte turunduslik. Kui ettevõte kasutab e-arveldajat ainult riigiasutustele e-arvete koostamiseks ja saatmiseks ega tee muid kandeid, on kasutamine tasuta ja e-arveid saab saata piiramatus koguses. Sama reegel kehtib ka siis, kui arveid luuakse rohkem, aga muid kandeid ei tehta.

Kes saab lepingu sõlmida: aktsiaseltsi, osaühingu, tulundusühistu, usaldusühingu, täisühingu, mittetulundusühingu, sihtasutuse ja Euroopa äriühingu juhatuse liikmed ning füüsilisest isikust ettevõtjad. Leping allkirjastatakse keskkonnas digitaalselt.

API on olemas ja see on REST

Levinud oletus on, et riigi tasuta raamatupidamistarkvaral liidest ei ole. RIKi abiinfo lehel on aga arendajale mõeldud tehniline dokumentatsioon, mille järgi on tegemist REST-teenustega, mille sisend ja väljund on JSON-vormingus ning kirjeldus OpenAPI 3.1 spetsifikatsiooni järgi YAML-vormingus.

/test.html on praktiliselt kõige kasulikum leht kogu liidese juures, sest allkirja genereerimine on see samm, kus esimene katse tavaliselt ebaõnnestub. Kui saad seal toimiva päringu, on sul olemas referents, mille vastu oma koodi võrrelda.

Võtme loomine: IP-aadress on kohustuslik väli

API võtit saab luua ainult kehtiva e-arveldaja lepinguga ettevõtte juhatuse liige, kes nõustub kasutustingimustega. Asukoht on Seadistused, üldised seadistused, e-arveldaja API juurdepääsuload.

Vormil on kolm kohustuslikku asja. Nimi, mis eristab võtit teiste seas. Lubatud IP-aadressid, mida saab sisestada mitu, semikooloniga eraldatult või vahemikena. Ja ligipääsetavad funktsioonid, kus vähemalt üks valik peab olema tehtud.

Võtme loomise järel saab selle alla laadida, andmeid muuta, kustutada ja vaadata päringute ajalugu. Ajalugu on hea tõendusmaterjal, kui keegi küsib, kes ja millal arveid muutis. RIK logib ka negatiivsed juurdepääsusündmused.

Autentimine: kaks päist ja üks allkiri

Iga päring kannab kahte HTTP-päist. X-AUTH-QUERYTIME sisaldab päringu tegemise aega UTC ajatsoonis sekundilise täpsusega, näiteks 2026-10-28T09:15:23. X-AUTH-KEY sisaldab kooloniga eraldatult võtme avalikku osa ja päringu allkirja.

Allkiri on BASE64(HMAC-SHA-384("apikeyid:aeg:url", ApiKeySalasõna)), kus apikeyid on võtme unikaalne identifikaator, aeg on sama väärtus, mis X-AUTH-QUERYTIME päises, ja url on teenuse absoluutne päringutee ilma protokolli ja serverinimeta, näiteks /v1/journals/62307/document_user.

X-AUTH-QUERYTIME: 2026-10-28T09:15:23
X-AUTH-KEY: <avalik võti>:<base64 allkiri>

allkiri = BASE64( HMAC-SHA-384(
  "530156f2101045438c8c3513eed6e893:2026-10-28T09:15:23:/v1/sale_invoices",
  ApiKeySalasõna
) )

Neli olukorda annavad 401: päis X-AUTH-KEY puudub, X-AUTH-QUERYTIME puudub või erineb serveri ajast viis minutit või rohkem kummaski suunas, allkiri ei ole kehtiv, või IP-aadressilt on logitud liiga palju negatiivseid sündmusi.

See tabel muudab ühe asja kohustuslikuks: kellaaja sünkroonimine. Kui kell erineb serveri ajast vähemalt viis minutit, ebaõnnestub autentimine. Korduvad vigased päringud võivad täita blokeerimise künnise: näiteks kümme negatiivset sündmust viie minuti jooksul. NTP peab töötama, ja kui see ei tööta, peab kood andma selge vea, mitte kordama päringut.

Mida API-ga päriselt saab teha

Spetsifikatsioon katab rohkem kui tavalise „saada arve“ vajaduse. Kirjutamistoiminguid toetab kaheksa põhiressurssi; ülejäänud üheksa on valdavalt loetavad, neist /invoice_info lubab ka PATCH-i.

Kaks otspunkti väärivad eraldi tähelepanu. /vat_info annab ettevõtte KMKR numbri ja EMTA maksuviitenumbri. Arverea vat_rate on ainult loetav ning käibemaksumäär tuletatakse toote seadistusest, seega eraldi maksu GUIDi siit ei tule. /accounts annab kontoplaani, mis on vajalik pearaamatu kannete ehitamiseks.

Nimekirjapäringutes saab kasutada page ja modified_since parameetreid vastavalt otspunkti kirjeldusele. Algus- ja lõppkuupäeva filtrid start_date ja end_date on olemas kannete, tehingute ning müügi- ja ostuarvete nimekirjadel; klientide ja toodete nimekirjadel neid ei ole. modified_since on sünkroonimise alus: hoia viimase õnnestunud päringu aeg ja küsi ainult muutunud objektid.

Arve voog: POST, register, deliver

Arve saatmine ei ole üks päring. Kolm sammu on kohustuslikud ja neil on eri tähendus.

1. Loo arve

   POST /v1/sale_invoices kehaga, mis sisaldab klienti, kuupäevi, arve numbrit ja ridu. Vastus annab objektile ID, mida järgmised sammud vajavad.

2. Registreeri arve

   PATCH /v1/sale_invoices/{id}/register. Registreerimata arve ei ole raamatupidamises kanne ja seda ei saa saata.

3. Küsi saatmisvõimalused

   GET /v1/sale_invoices/{id}/delivery_options annab can_send_einvoice, põhjuse väljal can_send_einvoice_reason, can_send_email ja pakutud e-posti aadressid.

4. Saada

   PATCH /v1/sale_invoices/{id}/deliver kehaga {"send_einvoice": true, "send_email": false}. Sama otspunkt saadab ka PDFi, kui send_email on true ja email_addresses täidetud.

PATCH /v1/sale_invoices/1698/deliver
{
  "send_einvoice": true,
  "send_email": true,
  "email_addresses": "ostja@example.com"
}

delivery_options võimaldab enne saatmist kontrollida, milline saatmisviis on lubatud ja mis seda takistab. Kui can_send_einvoice on false, ütleb põhjus, mida on vaja parandada, näiteks puuduv operaator või puuduv e-arve makse identifikaator kliendi kaardil. Ilma selle päringuta saadad e-arve, mis ei lähe kohale, ja klient ei tea sellest midagi.

Süsteemi genereeritud e-arve XML tuleb aadressilt GET /v1/sale_invoices/{id}/xml. See on kasulik siis, kui soovid arve sisu arhiveerida või edastada kolmandale osapoolele ilma, et peaksid ise XMLi genereerima.

Piirangud, mis tuleb ootustesse kirjutada

Spetsifikatsiooni muudatuste logi on selgesõnaline ja sellest saab välja lugeda, kuidas süsteem päriselt käitub.

• Registreeritud kande muutmine käib ringiga. Dokumenteeritud järjekord on invalidate, siis PATCH ja seejärel register. Otse muuta ei saa.
• Algbilanssi ei saa API-ga luua. POST /journals ignoreerib välja operation_type ja algbilansi kanne on kasutajaliidese hallata, sest ettevõttel saab olla ainult üks.
• Rea klassifikaatorid tulevad seadistustest. Alates 1. oktoobrist 2026 ignoreerib API sisendis välja andmesild_classifiers ja tuletab klassifikaatorid toote, konto, kliendi ja ettevõtte seadistusest. Kui kohustuslik rea klassifikaator puudub, vastab arve registreerimine koodiga 409.
• Ostuarve rea uuendamine asendab kõik read. Kui jätad välja cl_fringe_benefits_id, võetakse see kasutusele vaikeväärtusega 1, mis tähendab „soodustust ei ole“.
• Kanded ja tehingud tulevad enum-kujul. Postings.type on D või C, summad ei ole negatiivsed.

409 ei ole siin programmeerimisviga, vaid äriloogika vastus. Kood peab selle käsitlema nii, et kasutaja näeb, milline klassifikaator puudub, mitte üldist „midagi läks valesti“.

Operaatoriteenus tarkvaramüüjale

Kui sa ei ehita liidestust ühele ettevõttele, vaid tahad oma tarkvarale pakkuda e-arvete saatmist ja vastuvõttu, on RIKil selleks eraldi keskne operaatoriteenus. Liitudes ei pea sa eraldi liidestuma e-arvete vastuvõtjate registriga: RIK edastab sinna info ise, kui sinu tarkvara on end operaatoriks valinud.

Hind on 0,50 eurot kuus kliendi eest koos käibemaksuga, mida majandustarkvara maksab RIKile. E-arvete saatmine ja vastuvõtmine ise on seejuures tasuta. Kuutasu hakkab jooksma lepingu sõlmimisele järgneva kuu eest.

Kliendi poolel on üks samm, mida ei saa automatiseerida: ettevõtja peab ettevõtjaportaalis oma seose operaatoriga kinnitama. Alles pärast seda aktiveerub e-arvete vastuvõtmine võrgus.

Ainult nende operaatoritasude võrdluses on tükipõhine tasu odavam kuni nelja e-arve puhul kuus: neli arvet maksavad 24% käibemaksuga 0,496 eurot. Alates viiest arvest on 0,50-eurone kuutasu väiksem. 20 arve puhul on tasud 2,48 ja 0,50 eurot, 200 arve puhul 24,80 ja 0,50 eurot kuus. Need on eri teenusemudelid; valikus tuleb arvestada ka liidestuse ja raamatupidamistarkvara kulusid (RIK, Merit).

Kontrollnimekiri enne liidestamist

1. Kontrolli, kas e-arveldaja üldse sobib

   Kui on laoseisu, mitut valuutat põhjalikult või kontserni konsolideerimist, ei ole see õige alus. Liidestus ei laienda tarkvara funktsionaalsust.

2. Tee leping ja genereeri võti testkeskkonnas

   Juhatuse liige, seadistused, API juurdepääsuload. Sisesta lubatud IP kohe ka arenduskeskkonna jaoks, muidu kulub esimene päev IP-de taga ajamisele.

3. Võrdle oma allkirja /test.html tulemusega

   Sama aeg, sama päringutee, sama võti. Kui need kaks erinevad, on viga kas ajas või URLi kujus, mitte HMACis.

4. Ehita sünkroonimine modified_since peale

   Ära kopeeri kogu andmebaasi iga kord. Hoia viimast õnnestunud aega ja küsi ainult muutused.

5. Testi delivery_options enne deliver-i

   Ja kirjuta välja, mida teed siis, kui e-arve ei ole võimalik. Kõige levinum vastus on „saada PDF“, aga see peab olema otsus, mitte vaikeväärtus koodis.

Kui raamatupidamine on Merit Aktivas, loe edasi Merit Aktiva API juurest. Kui liidestus puudutab ka registriandmeid, on äriregistri API see, millega nimed ja registrikoodid enne arve väljastamist üle kontrollida. Kui vajad mõlemat korraga, ehita üks sisemine arvemudel ja kaks adapterit, mitte kaks eraldi voogu. Üldine tellimise pool on kirjas tarkvaraarenduse lehel.