Merit Aktiva API: ühenda Eesti raamatupidamine AI agendiga (2026)

Lühidalt: Merit Aktiva API on tasuta ja põhjalikult dokumenteeritud REST API, mis on saadaval alates Pro paketist. See kasutab HMAC-SHA256 allkirjastatud päringuid, tagastab JSON-i ja katab kõik olulised Eesti raamatupidamise osad: müügiarved, ostuarved, kliendid, artiklid, kontoplaani, palgaarvestuse ja käibedeklaratsiooni (KMD). Töötava API võtmega saab iga LLM, mis suudab teha HTTPS päringuid (Claude, ChatGPT, Cursor, n8n agendid), lugeda ja kirjutada otse Aktiva andmeid. Keeruline osa ei ole API ise, vaid mudelile Eesti spetsiifiliste reeglite õpetamine: KMD koodid, 2026. aastal kehtima hakanud 24% käibemaks, kontoplaan ja e-arve formaat. See artikkel käib läbi API tegeliku olemuse, autentimise, mis teeb enamikule esmakordsetele integreerijatele peavalu, ja kuus endpointi, mida läheb vaja juba esimesel nädalal.

Artikkel viitab ka avatud lähtekoodiga pluginile arturl95/merit-aktiva-skills, mis sisaldab juba kuut Claude Code'i oskust, mis on ehitatud otse selle API peale ja kuhu on Eesti maksureeglid sisse kirjutatud. See repo on olemas seetõttu, et nende reeglite iga kord nullist kirjutamine on ajaraiskamine.

Miks on API 2026. aastal olulisem kui eelmisel aastal

Kaks asja muutusid. Esiteks tõusis Eesti standardne käibemaksumäär 22% pealt 24% peale ja see muudatus mõjutab iga KMD koodi, iga vaikimisi maksuseadistust ja iga salvestatud arvepõhja. Tarkvara, mis oli detsembris õige, on jaanuaris vaikimisi vale, kui keegi ei ole käinud reegleid üle kontrollimas. Teiseks on iga raamatupidamise töövoog nüüd kättesaadav AI agendile, mis suudab lugeda PDF-e, mõista konteksti ja teha API päringuid. See tähendab, et töö, mis varem nõudis nooremraamatupidajat ja Make.com stsenaariumi, on nüüd tehtav ühe Claude'i või ChatGPT sessiooniga algusest lõpuni, kui see oskab Aktivaga suhelda.

Merit avaldab oma API avatult. Dokumentatsioon asub aadressil api.merit.ee. Konks on aga selles, et dokumentatsioon eeldab, et sa juba mõistad Eesti raamatupidamist ja oled arendaja, kes loeb viitematerjali, mitte ehitaja, kes püüab AI agenti ühendada. Lõhe "siin on spetsifikatsioon" ja "siin on töötav integratsioon" vahel ongi see, mis inimestele komistuskiviks saab.

Nõuded paketile ja kuidas saada API võtit

Merit Aktiva API on tasuta, aga ainult alates Pro paketist. Standard pakett ei paku API ligipääsu. See on kõige levinum põhjus, miks esimene katse ebaõnnestub: loetakse, et API on tasuta, genereeritakse võti ja seejärel saadakse 401 veakood, sest ettevõttel on vale pakett.

Võtme genereerimiseks Aktivas tuleb teha järgmist:

1. Logi sisse oma Aktiva ettevõttesse.
2. Ava Seadistused -> Üldised seadistused -> API.
3. Klõpsa Lisa uus API kasutaja. Aktiva tagastab kaks väärtust: API ID ja API Key (base64 formaadis jagatud saladus).

Salvesta mõlemad. API ID läheb päringusse query parameetrina. API Key ei lahku kunagi sinu serverist, seda kasutatakse päringute allkirjastamiseks, mitte ei edastata.

Autentimine: HMAC-SHA256 ja ajatempli lõks

Iga API päring vajab query stringis kolme asja: ApiId, timestamp ja signature. Allkiri (signature) on HMAC-SHA256 räsistring, mis on kokku pandud väärtustest ApiId + timestamp + body, kodeeritud base64 formaati ja kus HMAC saladusena kasutatakse sinu API Key väärtust.

Siin on kaks konksu, mille otsa peaaegu kõik komistavad:

Ajatempli formaat. Merit ootab formaati yyyyMMddHHmmss UTC ajas. Mitte ISO 8601, mitte kohalikku aega, mitte eraldajatega. 20260115143022 töötab. 2026-01-15T14:30:22Z ei tööta.

GET päringute sisu (body). Kui teed GET päringu, on body tühi string ". See tuleb ikkagi stringiga kokku panna. Inimesed kipuvad seda unustama ja söödavad HMAC-ile sisse null väärtuse, mis toodab serveri oodatust erineva allkirja.

Minimaalne Pythoni näide:

import hmac, hashlib, base64, json
from datetime import datetime, timezone
import requests

API_ID = "your-api-id"
API_KEY = "your-api-key"
BASE = "https://aktiva.merit.ee/api/v2"

def sign(body: str) -> tuple[str, str]:
    ts = datetime.now(timezone.utc).strftime("%Y%m%d%H%M%S")
    msg = (API_ID + ts + body).encode("utf-8")
    sig = base64.b64encode(
        hmac.new(API_KEY.encode("utf-8"), msg, hashlib.sha256).digest()
    ).decode("utf-8")
    return ts, sig

# Fetch the customer list
ts, sig = sign(")
r = requests.get(
    f"{BASE}/getcustomers",
    params={"ApiId": API_ID, "timestamp": ts, "signature": sig},
)
print(r.json())

Sama muster curl-iga, kus body on arvutatud JSON stringina:

BODY='{"PeriodStart":"2026-01-01","PeriodEnd":"2026-01-31"}'
TS=$(date -u +%Y%m%d%H%M%S)
SIG=$(printf '%s' "${API_ID}${TS}${BODY}" \
  | openssl dgst -sha256 -hmac "$API_KEY" -binary \
  | base64)

curl -s "https://aktiva.merit.ee/api/v2/getsalesinvoices?ApiId=${API_ID}&timestamp=${TS}&signature=${SIG}" \
  -H "Content-Type: application/json" \
  -d "$BODY"

Kui allkiri on vale, vastab API koodiga 401. Kui ajatempel on Meriti serveri kellast rohkem kui viis minutit nihkes, on vastus samuti 401. Allkirjasta päring alati vahetult enne saatmist.

Kuus endpointi, mida sa esimesel nädalal päriselt kasutad

Täielikus viitejuhendis on kümneid endpointe. Praktikas piisab integratsiooni käivitamiseks kuuest.

SendInvoice. Loob müügiarve. Võtab vastu kliendi viite (olemasoleva või uue), arveread koos tootekoodi (SKU) ja hinnaga ning KMD koodi iga rea kohta. Kõige levinum viga on siin TaxId ära jätmine realt. Aktiva võtab päringu küll vastu, aga arve salvestub vale käibemaksumääraga ja KMD aruanne läheb valeks täpselt nii mitme arve võrra, kui sa importisid.

SendPurchaseInvoice. Sama struktuur, aga vastupidises suunas. Kasutatakse tšekkide ja hankijate ostuarvete importimiseks, sageli pärast OCR sammu.

GetSalesInvoices / GetPurchaseInvoices. Lehekülgedeks jagatud (paginated) päringud kuupäevavahemiku filtritega. Kasuta neid sobitamiseks, töölaudade (dashboards) jaoks ja andmete söötmiseks tagasi LLM-ile, mis peab vastama küsimustele nagu "kui palju me kulutasime esimeses kvartalis serveriteenustele".

GetCustomers / SendCustomer. Klientide põhiandmed. Väli RegNo on Eesti ettevõtte registrikood. Aktiva suudab selle põhjal topeltkandeid vältida (deduplicate), kui sa seda lubad.

GetItems / SendItem. Artiklite põhiandmed, sealhulgas vaikimisi käibemaksumäär. Kui müüd digiteenuseid EL-i klientidele, siis just artikli taseme käibemaksu seadistustes konfigureeritakse pöördmaksustamine.

GetGLTransactions. Toores pearaamat. Endpoint, mida esimesel päeval peaaegu keegi ei kasuta, kuid mis muutub asendamatuks esimesel korral, kui AI agent peab vastama päris auditi küsimusele.

Ei ole olemas sellist SendGLTransaction endpointi, mis pakuks raamatupidajale korrigeerimiskanneteks vajalikku detailsust. API eeldab, et sa saadad äritehinguid (arved, maksed) ja lased Aktival ise pearaamatu kanded tuletada. See on taotluslik ja õige disain, kuid see üllatab inimesi, kes tulevad süsteemidest, kus saab otse pearaamatu kandeid teha.

Mida sa pead mudelile õpetama

See on osa, mida ametlik dokumentatsioon ei kata, sest see on kirjutatud inimarendajatele, kes tunnevad Eesti raamatupidamist. AI agent seda ei tunne.

KMD koodid. Eesti käibedeklaratsioon kasutab iga lahtri jaoks numbrilisi koode: 1 on standardmääraga müük, 2 on vähendatud määr, 3 on nullmääraga EL-i müük, 4 kuni 7 on erinevad pöördmaksustamise juhud ja nii edasi. Mudel ei suuda neid õigesti ära arvata. Need peavad olema süsteemiviibas (system prompt) või oskuse (skill) juhistes.

2026. aastal kehtima hakanud 24% käibemaksumäär. Internetis leiduvad sissekodeeritud näited näitavad endiselt 22%. Kui agent kasutab maksumäärade määramiseks oma treeningandmeid, mitte ei tee päringut Aktiva maksuseadistuste endpointi, on iga tema loodud arve vale. Selle parandamiseks tuleb kas pärida aktiivne käibemaksumäär iga sessiooni alguses või kirjutada 24% agendi viitedokumentidesse sisse ja uuendada seda siis, kui Eesti järgmine kord maksumäära muudab.

Kontoplaan. Aktiva tuleb standardse Eesti kontoplaaniga, kuid lubab seda kohandada. Agent vajab ettevõttespetsiifilist kontoplaani, mitte üldist, ja ta peab teadma, millised kontod milliste tehingutega seotud on. Endpoint getaccounts tagastab selle info; puhverda (cache) see sessiooni alguses.

E-arve formaat. Eesti kasutab e-arvete jaoks spetsiifilist XML-skeemi, mis on sarnane, kuid mitte identne EL-i PEPPOL profiiliga. Aktiva suudab API kaudu e-arveid nii saata kui ka vastu võtta, kuid väljade vastendamine on kapriisne. Enamik integratsioone jätab e-arvete haldamise Aktiva enda hooleks, selle asemel et agendis XML-i kokku panna.

Reaalne näide: Claude loob loomulikust keelest müügiarve

Kasutaja ütleb: "Tee arve ettevõttele Estonian Design OÜ 40 tunni konsultatsioonide eest hinnaga 95 eurot tund, töö tehtud jaanuaris, maksetähtaeg 14 päeva, saada e-postiga."

Ilma õige oskuseta ei ole Claude'il aimugi, millist TaxId väärtust panna, kas Estonian Design OÜ on juba kliendibaasis olemas, millist valuutat või KMD koodi rakendada ega seda, kuidas päringut allkirjastada.

Oskusega, mis sisaldab API viiteid, KMD koodide tabelit, aktiivset 24% käibemaksumäära ja kliendi otsimise mustrit, teeb Claude järgmist:

1. Kutsub välja GetCustomers filtriga Name=Estonian Design, leiab olemasoleva kirje ja võtab kliendi ID.
2. Paneb kokku arve andmed (payload): üks rida, 40 ühikut, 95 EUR ühiku kohta, KMD kood 1 (standardmäär), TaxId 24% jaoks, maksetähtaeg täna + 14 päeva, e-postiga saatmise lipp (flag) on sisse lülitatud.
3. Allkirjastab ja saadab päringu endpointi SendInvoice.
4. Kinnitab kasutajale arve numbri.

Koguaeg: alla viie sekundi. Raamatupidaja näeb arvet Aktivas ja kas kinnitab selle sellisena, nagu see on, või muudab enne saatmist. See ongi see töötsükkel, mille pärast tasub integratsiooni ehitada.

Mida API ei tee

Mõned asjad, mis inimesi üllatavad:

API-l on päringusagedus (rate limiter) piiratud. Merit avaldab piirangud aadressil api.merit.ee/connecting-robots/reference-manual/. Enamiku agendi kasutusjuhtude jaoks on piirangud helded, kuid 10 000 ajaloolise arve massimporti tuleb teha osade kaupa.

API ei toeta webhooke. Ei ole olemas "arve makstud" tõuketeavitust (push notification). Kui vajad sündmuspõhist (event-driven) käitumist, pead regulaarselt pärima GetSalesInvoices viimase kuupäeva filtriga ja võrdlema seda oma viimati nähtud seisuga.

API ei saa käivitada panga otseühendust. Kui soovid, et AI agent impordiks pangatehinguid, siis panga ja Aktiva otseühendus jookseb Aktiva poolel ning agent näeb tulemust alles tagantjärele läbi GetGLTransactions endpointi.

Millal API täielikult vahele jätta

Kõigepealt aus vastus. Kui kasutusjuht on ühekordne "tahan oma ostuarved e-postist Aktivasse saada", siis Envoice koos Aktiva otseühendusega teeb seda juba praegu, see vajab ühekordset seadistamist, ei nõua koodi kirjutamist ja on tasuta. Kui kasutusjuht on üks staatiline ja kindla kujuga töövoog, näiteks "igast Stripe'i maksest saab müügiarve", siis on Make.com stsenaarium kiirem ehitada ja mitte-arendajal lihtsam hooldada.

API koos AI agendiga on õige vastus siis, kui töövoog vajab otsustusvõimet: struktureeritud andmete eraldamine ettearvamatutes formaatides PDF-idest, ad-hoc finantsküsimustele vastamine vestluses, fikseeritud stsenaariumi jaoks liiga keeruliste reeglite rakendamine või raamatupidajale võimaluse andmine suhelda agendiga loomulikus keeles.

Eraldi artikkel käib detailselt läbi Make vs n8n vs AI agent otsustusprotsessi.

Valmis lähtepunkt

Autentimise, endpointide wrapperite, KMD koodide viidete, 2026. aasta maksureeglite ja klientide/artiklite topeltkannete vältimise loogika nullist kirjutamine võtab umbes nädala. Ükski neist ei ole huvitav töö. Repositoorium aadressil github.com/arturl95/merit-aktiva-skills pakendab selle kõik kuueks Claude Code'i oskuseks: raamatupidamine, arveldamine, KMD, palgaarvestus, e-arvete haldamine ja audit. Oskused on avatud lähtekoodiga MIT litsentsi all, kakskeelsed (inglise ja eesti) ning neid uuendatakse, kui maksureeglid muutuvad. Need ei ole teek (library), mida sa välja kutsud, vaid juhised, mida AI agent loeb, et õppida selgeks API ja Eesti reeglid. Lisa need Claude Code'i käsuga /plugin install, seadista kaks keskkonnamuutujat (MERIT_API_ID ja MERIT_API_KEY) ning agent saab kohe Aktivaga rääkida.

Need oskused ei asenda päris raamatupidajat. Need asendavad käsitsi andmesisestust ja rutiinset API torutööd.

KKK

Kas Merit Aktiva API on tasuta? Jah, alates Pro paketist. Standard paketi klientidel ei ole API ligipääsu.

Milline Aktiva pakett annab mulle API ligipääsu? Pro ja Premium. Paketti saab muuta Aktiva arvelduse seadete all; API võti muutub kehtivaks alles pärast paketi uuendamist.

Kuidas ma saan Merit Aktiva API võtme? Logi sisse Aktivasse, ava Seadistused -> Üldised seadistused -> API, klõpsa Lisa uus API kasutaja ning kopeeri nii API ID kui ka API võti.

Kas ma saan ühendada Merit Aktiva ChatGPT või Claude'iga? Jah. Iga AI agent, mis suudab teha allkirjastatud HTTPS päringuid, saab API-ga suhelda. Keeruline osa on agendile Eesti reeglite (KMD koodid, 24% käibemaks, kontoplaan) õpetamine. Avatud lähtekoodiga merit-aktiva-skills plugin hoolitseb selle eest.

Kas Merit Aktiva API toetab e-arveid? Jah, nii saatmist kui ka vastuvõtmist. Praktikas jätavad enamik integratsioone e-arve XML-i haldamise Aktiva enda hooleks ja lihtsalt käivitavad saatmise läbi API.

Kas Make.com, n8n ja Zapier töötavad Merit Aktivaga? Neile ei ole ametlikke konnektoreid. Kõik kolm töötavad läbi üldiste HTTP päringu sõlmede (nodes) koos reaalajas arvutatud HMAC allkirjastamisega. n8n on kõige lihtsam, sest sellel on sisseehitatud krüpto sõlm.

Miks minu allkiri tagastab pidevalt 401 veakoodi? Kolm põhjust tõenäosuse järjekorras: ajatempel ei ole yyyyMMddHHmmss UTC formaadis, body on HMAC-i arvutamisel kokku panemata jäänud (eriti null tühja stringi asemel GET päringute puhul), API võti on kopeeritud koos reavahetusega (trailing newline).

Kas on olemas liivakast (sandbox)? Merit pakub soovi korral eraldi testettevõtet. Enamiku varajaste integratsioonitööde jaoks on kiireim viis luua uus prooviperioodiga Aktiva ettevõte ja kasutada selle päris API-t.