Merit Aktiva API: tehingust e-arveni ilma käsitsi tööta

Mida Merit Aktiva API teeb ja mida mitte

Merit Aktiva API on REST-liides, mis vahetab JSONi üle HTTPSi. Kaks sisenemispunkti: https://aktiva.merit.ee/api/v1/ ja https://aktiva.merit.ee/api/v2/. Poola lokaliseeringu jaoks on eraldi host, Eesti ettevõttele piisab Eesti omast. V2 toetab dimensioone. Mitme maksega arve jaoks on dokumenteeritud eraldi otspunkt POST /api/v1/sendinvoice2, mille sisendis on massiiv Payments; juba loodud arvele saab makseid osade kaupa lisada ka /api/v2/sendpayment kaudu.

Kolm asja, mida dokumentatsioon ütleb ja mida tasub enne arhitektuuriotsust teada. API töötab ainult Pro- ja Premium-litsentsiga; madalama paketi korral tuleb 401 koodiga api-wronglicense. API-võti ja ID luuakse iga liidestatava tarkvara jaoks eraldi, seega üks võti ühe süsteemi kohta, mitte üks võti kõige jaoks. Ja võtit saab luua ainult peakasutaja.

Piir kahe süsteemi vahel ei ole ainult tehniline küsimus. Enne koodi kirjutamist tasub integratsiooni poolelt läbi mõelda, kas arve tuleb luua Merit Aktivas või on Merit ainult sihtkoht, kuhu arved jõuavad.

Mida API ei tee: see ei asenda e-arve operaatorit. Arve loomine ja arve saatmine e-arvena on kaks eraldi sammu, ja teine samm töötab ainult siis, kui operaatori seadistus on tehtud ning vastuvõtja saab e-arveid vastu võtta.

Autentimine: kolm parameetrit ja üks allkiri

Merit ei kasuta API-võtit päises. Iga päring kannab kolme päringustringi parameetrit: apiId, timestamp ja signature. Allkiri arvutatakse HMAC-SHA256-ga, võtmega apiKey, andmetest apiId + timestamp + keha, ja kodeeritakse base64-sse.

Päringu ajatempel (timestamp) peab olema UTC ajas kujul yyyyMMddHHmmss ja vastama päringu tegemise hetkele. Eesti suveajal tähendab see, et kohalikust kellaajast tuleb kolm tundi maha lahutada. Vananenud või tulevikus olev ajatempel lükatakse tagasi ja see viga tabab arendajat tavaliselt esimesel toodangupäeval, mitte testis.

import { createHmac } from "node:crypto";

const apiId = process.env.MERIT_API_ID;
const apiKey = process.env.MERIT_API_KEY;

function signedQuery(body = "") {
  const timestamp = new Date().toISOString().replace(/[-:T]/g, "").slice(0, 14);
  const signature = createHmac("sha256", apiKey)
    .update(apiId + timestamp + body)
    .digest("base64");
  return new URLSearchParams({ apiId, timestamp, signature }).toString();
}

const qs = signedQuery();
await fetch(`https://aktiva.merit.ee/api/v2/taxes?${qs}`);

Allkiri võib sisaldada märke, mis tuleb URLis kodeerida. URLSearchParams teeb selle ära; käsitsi kokku pandud string mitte, ja siis tekib 401, mille põhjus on plussmärk, mitte võti.

Keha allkirjastatakse täpselt nendes baitides, mis teele lähevad. Kui serialiseerid objekti kaks korda ja vahepeal muutub võtmete järjekord või tühikute arv, saad allkirja, mis ei vasta kehale. Praktiline reegel: serialiseeri üks kord, hoia string muutujas, saada see string ja allkirjasta sama string.

Enne arvet: maksu GUID

Arve ridade juures on TaxId kohustuslik ja see on GUID, mitte protsent. GUIDid tulevad aadressilt GET /api/v2/taxes. Vastus loetleb kõik ettevõtte maksuseadistuses olevad määrad: Id, Code, Name, TaxPct, NonActive, CountryId.

Õige muster on see GUID üks kord välja lugeda, vastendada oma süsteemis käibemaksumääraga ja hoida vastendus konfiguratsioonis. Kui iga arve loomise ajal maksunimekirja pärida, kulub kaks päringut ühe asja eest ja 100 päringu minutipiirangust saab kiiresti kitsas koht.

Kaks dokumenteeritud nõuet, mis päriselt ka põhjustavad vigu. Esiteks peab iga arve rida olema oma maksugrupis ja TaxAmount massiiv peab olema summeeritud TaxId kaupa. Teiseks ei tohi erineva käibemaksumääraga kaupu ja teenuseid summeerida sama kaubakoodi alla, sest siis ei lähe maksudeklaratsioon kokku.

Arve loomine: POST /api/v2/sendinvoice

Minimaalne toimiv päring sisaldab arve numbrit, kuupäevi, klienti, ridu ja maksusummasid. Allpool on lühendatud päringu näide; vajalikud väljad tuleb üle kontrollida kasutatava versiooni dokumentatsioonist.

POST /api/v2/sendinvoice?apiId=...&timestamp=...&signature=...

{
  "Customer": {
    "Name": "Näidis OÜ",
    "RegNo": "12345678",
    "NotTDCustomer": false,
    "VatRegNo": "EE123456789",
    "CurrencyCode": "EUR",
    "PaymentDeadLine": 14,
    "CountryCode": "EE"
  },
  "DocDate": "20261028",
  "DueDate": "20261111",
  "InvoiceNo": "ARVE-2026-0412",
  "InvoiceRow": [
    {
      "Item": { "Code": "TEENUS", "Description": "Kuu hooldus", "Type": 2 },
      "Quantity": 1,
      "Price": 500.0,
      "DiscountPct": 0,
      "TaxId": "<guid /api/v2/taxes vastusest>"
    }
  ],
  "TotalAmount": 500.0,
  "TaxAmount": [{ "TaxId": "<sama guid>", "Amount": 120.0 }]
}

Kliendi plokil on kolm kasutusjuhti, mis käituvad erinevalt. Kui annad ainult Name, otsib Merit olemasolevat klienti nime järgi ja kui ei leia, loob uue. Kui annad CustomerId, kasutab Merit olemasolevat kirjet ja ülejäänud väljad ei loe. Kolmas variant on segu: ID puudub, aga nimi on olemas ja Merit võtab andmed kliendikaardilt, mitte päringust.

NotTDCustomer on Eesti puhul true füüsilistele isikutele ja välisettevõtetele. See väli mõjutab seda, kuidas arvet deklaratsioonides käsitletakse, ja vale väärtus on vaikne viga, mis ilmub alles KMD-l.

Vastus on lühike ja seda tasub alati salvestada: CustomerId, InvoiceId, InvoiceNo, RefNo, NewCustomer. InvoiceId on ainus võti, millega hiljem arvet e-arvena saata või selle PDFi küsida. RefNo genereeritakse, kui seda ei anna, aga dokumentatsioon palub selle ise valideerida.

Kui soovid arve kohe ka makstuks märkida, lisa Payment plokk: PaymentMethod (peab olema ettevõtte seadistuses olemas), PaidAmount koos käibemaksuga ja PaymDate. Seda kasutatakse juhul, kui arve luuakse alles pärast õnnestunud makset.

E-arvena saatmine: sendinvoiceaseinv

E-arve saatmine on eraldi päring: POST /api/v2/sendinvoiceaseinv kehaga {"Id": "<SIHId>", "DelivNote": false}. Üks päring, üks arve. DelivNote väärtusega true saadab arve ilma hindadeta, mis sobib saateleheks.

Õnnestumine annab vastuseks OK. Kui vastuvõtja ei saa e-arveid vastu võtta, tuleb api-noeinv. See ei ole viga sinu koodis ja seda ei paranda korduskatse: põhjus on vastuvõtja poolel. Käsitle seda olekuna, mis läheb järjekorda ja proovib hiljem uuesti, ning saada samal ajal kliendile PDF.

Kliendikaardil on e-arve jaoks kolm välja, mis tuleb enne saatmist paika panna: EInvPaymId (makse identifikaator), EInvOperator ja BankAccount. Operaatori koodid on dokumenteeritud: 1 ei ole, 2 e-arved panka läbi Omniva, 3 pank täies ulatuses, 4 pank piiratud ulatuses.

Ostuarvete vastuvõtmine ei hakka tööle enne, kui operaator on äriregistris kinnitatud. Telema puhul saadab Merit sama päeva õhtul operaatori info registrisse ja ettevõtte allkirjaõiguslik isik kinnitab selle järgmisel päeval ettevõtjaportaalis. See üks päev on realistlik plaanimisalus, mitte ebameeldiv üllatus.

Piirid, mis kujundavad integratsiooni

Neist neljast tuleneb üks otsus: ehita sündmusepõhine integratsioon, mitte perioodiline täisskaneerimine. Kui CRM saadab arve loomise sündmuse, teeb sinu teenus ühe sendinvoice päringu ja ühe sendinvoiceaseinv päringu. Kui tahad öösel kõike võrrelda, kasuta müügiarvete getinvoices päringus DateType väärtust 1 (Changeddate) ning jaga periood sobivateks ajavahemikeks.

Korduste kaitse, mida API ise ei anna

Merit Aktiva API dokumentatsioonis ei ole idempotentsusvõtit. Kui võrk katkeb pärast seda, kui server on arve loonud, ei tea sinu kood, kas arve tekkis. Enne kordussaatmist kontrolli, kas arve on olemas, ning töötle sama arvenumbri saatmist korraga ainult ühes töös. Päringule järgnev loomine ei ole atomaarne: kaks paralleelset töötlejat võivad mõlemad saada tühja vastuse ja luua topeltarve.

1. Kontrolli, kas arve on juba olemas

   Päri /api/v2/getinvoices2 väljaga InvNo ja vaata, kas vastus on tühi. See on üks lisapäring, aga odavam kui topeltarve.

2. Saada arve ja salvesta InvoiceId

   Kirjuta oma andmebaasi InvoiceNo, InvoiceId, CustomerId ja vastuse aeg. Ilma InvoiceId-ta ei saa e-arvet hiljem saata.

3. Saada e-arve eraldi sammuna

   Ebaõnnestunud e-arve ei tähenda, et arve ise ei tekkinud. Hoia need kaks olekut lahus ja korda ainult teist sammu.

4. Nummerda arved oma süsteemis

   Kui InvoiceNo genereeritakse Meritis, kaob võimalus kordust ära tunda numbri järgi. Anna number ise ja hoia see unikaalsena.

Mida see päriselt maksma läheb

Kaks kulu liiguvad koos: Merit Aktiva litsents, mille Pro või Premium tase on API eeldus, ja operaatoritasu iga e-arve eest. Viimase saab arvutada täpselt, sest Merit avaldab selle numbri.

Käibemaks on Eestis alates 1. juulist 2025 24 protsenti. Arvutuse mõte ei ole hirmutada, vaid näidata, et operaatoritasu kasvab lineaarselt ja jääb väikeseks kuni umbes tuhande arve piirini kuus. Suurema mahu juures tasub kaaluda otselepingut operaatoriga, sest Merit vahendab seda edasi ja lisab oma rea.

Millal Merit Aktiva API ei ole õige valik

Kui ettevõte on alles alustanud ja raamatupidamine käib e-arveldajas, ei ole Merit API mõttekas: e-arveldaja tavakasutus on esimesel aastal tasuta; hiljem maksab kuni kümne kande kuus tegija 5 eurot aastas ja suurema mahu korral algab tasu 5 eurost kuus, millele lisandub käibemaks. Kui ettevõtte raamatupidamine on Directos, tuleb lähtuda Directo liidesest. e-Financials on RIKi e-arveldaja ingliskeelne nimi, mitte eraldi tarkvara.

Valik ei ole tehniline ega käi API ilu järgi. Kui raamatupidaja töötab Merit Aktivas, ehita Meritile. Kui raamatupidaja töötab e-arveldajas, ehita sinna. Kaks liidestust korraga tähendab kahte tõde samade arvete kohta ja seda ei kannata ükski kuuaruanne.

Kontrollnimekiri enne esimest päringut

1. Kontrolli litsentsi ja loo võti

   Pro või Premium, seejärel Seadistused, ettevõtte andmed, API seadistus. Loo eraldi võti just selle süsteemi jaoks ja pane kommentaari süsteemi nimi.

2. Loe maksu GUIDid välja ja vastenda need

   GET /api/v2/taxes, seejärel vastendus käibemaksumääradega oma koodis. Ilma selleta ei lähe ükski arve läbi.

3. Kirjuta allkirjastaja nii, et keha serialiseeritakse üks kord

   Üks string, üks allkiri, üks päring. See hoiab ära kõige sagedasema 401 põhjuse.

4. Sea sisse 429 käsitlus uue timestampiga

   Loe Retry-After päis, oota, arvuta uus timestamp, proovi uuesti. Ilma uue timestampita korduskatse ebaõnnestub.

5. Testi e-arve saatmist operaatori testkontoga

   Kontrolli EInvOperator väärtust ja api-noeinv käsitlust enne, kui päris kliendid arveid saavad. Kui aktiveerid enda ettevõttele Telema kaudu ostuarvete vastuvõtu, saab allkirjaõiguslik isik operaatori seose Meriti juhendi järgi järgmisel päeval registris kinnitada.

Kui arved liiguvad edasi muudesse süsteemidesse, vaata ka e-arveldaja liidestamist ja API integratsioonide ülevaadet. Üldine tellimise pool on kirjas tarkvaraarenduse lehel: seal on ka see, mida ma integratsiooni juures alati enne töö algust kontrollin.