API konventsioonid

Päringute kuju

Iga toiming on RPC-laadne POST-päring:

POST /v1/{module}/{resource}/{action}

Moodulid: reference, partners, catalog, sales, purchases, ledger, bank, declarations, files, webhooks, audit. Toimingud on verbid: create, get, update, delete, list ning domeenipõhised toimingud nagu issue, register, match, apply-advance, generate.

Autentimine ja õiguse ulatuse (scopes)

Authorization: Bearer <api key>. Võtmetel on õiguse ulatused (scopes), mida kontrollitakse iga toimingu puhul:

• {module}:read - pärimis- ja loendustoimingud
• {module}:write - andmeid muutvad toimingud
• {module}:* või * - metamärgid (wildcards)

Puuduv õiguse ulatus → 403 forbidden. Puuduv või vigane võti → 401 unauthorized.

Loendipäringud

Kõik list-toimingud kasutavad ühtset lepingut:

{
  "page": 1,
  "pageSize": 50,
  "sort": [{ "field": "createdAt", "dir": "desc" }],
  "filter": [{ "field": "paymentStatus", "op": "eq", "value": "unpaid" }]
}

Filtreerimisoperaatorid: eq (võrdne), ne (ei ole võrdne), contains (tõstutundetu tekstivaste, ainult tekstiväljad), gte (suurem või võrdne), lte (väiksem või võrdne), in (ükskõik milline väärtus kuni 500 väärtusest koosnevast loendist). Sorteeritavad ja filtreeritavad väljad on otspunktide kaupa lubatud loendis (vt OpenAPI spetsifikatsiooni); tundmatud väljad tagastavad veakoodi 400. Lisage päringule totals: ["field", …], et summeerida numbrilisi välju kõigi vastavate kirjete lõikes; kui kirjetel on määratud valuuta, tagastab totalsByCurrency samad summad valuutakoodide kaupa eristatuna. Vastused: { rows, total, page, pageSize, totals?, totalsByCurrency? }.

Raha ja kuupäevad

Rahasummad on kümnendmurruna esitatud stringid kuni 4 komakohaga ("121.0000"), mitte kunagi ujukomaarvud. Käibemaks arvutatakse rea kaupa, kasutades pool ülespoole ümardamist (half-up rounding). Kuupäevad on vormingus YYYY-MM-DD; ajahetked (timestamps) on ISO 8601 UTC formaadis.

Vead

Kõik vead on ühesuguse ümbrisega:

{
  "error": {
    "code": "validation",
    "message": "Request validation failed",
    "requestId": "k1x…",
    "key": "request_invalid",
    "fieldErrors": { "lines.0.unitPriceExclVat": ["Invalid value"] }
  }
}

Koodid: validation (400/422 ning 413, kui üleslaaditud fail või päringu sisu on liiga suur), unauthorized (401), payment_required (402, prooviperiood või ettemakse on lõppenud; sõnum selgitab, kuidas jätkata), forbidden (403), not_found (404), conflict (409), idempotency_key_reuse (422), idempotency_in_progress (409), rate_limited (429), internal (5xx). Kui tegemist on eelmääratletud süsteemse sõnumiga, nimetab key selle ära, et klient saaks kuvada oma tõlget, ning params sisaldab sõnumisse paigutatavaid väärtuseid (näiteks { "period": "2026-09" } lukustatud aruandeperioodi puhul). Probleemidest teatamisel lisage kindlasti requestId.

Identsuspäringud (idempotency)

Lisage mis tahes andmeid muutuvale päringule päis Idempotency-Key: <mis tahes string kuni 255 tähemärki>:

• Korduv päring sama võtme ja sisuga - salvestatud vastus esitatakse uuesti bait-baidilt koos päisega x-idempotent-replay: true.
• Sama võti, erinev sisu - 422 idempotency_key_reuse.
• Samaaegne duplikaatajal, mil esimene päring on alles pooleli - 409 idempotency_in_progress.
• Võtmed kuuluvad päringu saatvale API võtmele või kasutajale selle ettevõtte raames, mille nimel tegevus toimub, nii et ühe ettevõtte kaks integratsiooni saavad kasutada sama võtit. Enne ettevõtte loomist tehtud päringud ja account/* päringud seovad võtmed kasutajapõhiselt, mistõttu korduv account/companies/create loob ainult ühe ettevõtte.
• Salvestatud vastus tagastatakse alles siis, kui päringu esitaja läbib uuesti samad õiguste kontrollid (õiguse ulatus, roll, ettevõte ja arveldusstaatus); vastasel juhul tagastatakse praegune veateade.
• Võtmed aeguvad 24 tunni pärast. Veavastused (4xx) esitatakse samuti uuesti; 5xx vastuseid ei salvestata, nii et katsed tehakse uuesti.

Päringupiirangud (rate limits)

300 päringut minutis API võtme kohta (esitatud autentimisandmete alusel; autentimata päringuid piiratakse IP-aadressi alusel). Veakoodi 429 saamisel järgige päist retry-after. Päised x-ratelimit-* annavad ülevaate teie limiitide jäägist.

Veebikonksud (webhooks)

Sündmused salvestatakse tehingupõhisesse väljaminevate teadete vahemällu (transactional outbox) samas andmebaasitehingus muudatusega – tagasipööratud (rolled-back) dokument ei tekita kunagi sündmust ja ükski sündmus ei lähe kaduma. Edastamine:

• POST-päring teie URL-ile koos sündmuse JSON-andmetega
• x-nordlet-timestamp: <unix seconds> - aeg, millal edastus allkirjastati
• x-nordlet-signature-v2: t=<timestamp>,v1=<hex HMAC-SHA256 of "<timestamp>.<raw body>">, kasutades teie tellimuse salajast võtit (secret)
• x-nordlet-signature: sha256=<hex HMAC-SHA256 of the raw body> - säilitatud muutumatul kujul olemasolevate vastuvõtjate jaoks
• x-nordlet-delivery sisaldab edastuse ID-d, mis on sama ühe edastuse kõigi korduskatsete puhul
• Muu kui 2xx vastuse või ümbersuunamise korral proovitakse uuesti 30 sekundi, 2 minuti, 10 minuti, 30 minuti, 1 tunni, 3 tunni, 6 tunni ja 12 tunni pärast (kokku umbes 24 tundi), enne kui edastus märgitakse ebaõppenuks
• Iga edastust saadab korraga üks server, mistõttu mitme API eksemplari käitamine ei saada seda topelt

Enne sisu usaldamist kontrollige x-nordlet-signature-v2 ajas konstantse võrdlusega (constant-time comparison) ning lükake tagasi edastus, mille ajatempel erineb teie kellaajast rohkem kui 5 minutit. Ajatempel on allkirjastatud teksti osa, mistõttu püütud edastust ei saa hiljem uue ajatempliga uuesti esitada. Salvestage töödeldud x-nordlet-delivery ID-d, et ignoreerida kordusi selle ajavahemiku jooksul. Ebaõnnestunud edastuse saab uuesti saata päringuga webhooks/deliveries/redeliver.

Audit

Iga andmemuudatus logitakse (actor, action, entity, diff) ja seda saab pärida otspunkti audit/list kaudu.

Raamatupidamise tagatised

• Kanned on alati tasakaalus – seda tagab edasilükatud andmebaasitrigger (deferred database trigger) tehingu kinnitamise (commit) hetkel, mitte ainult rakenduse kood.
• Dokumendinumbrid on seeria/aasta lõikes katkematud ja numbrite eraldamine on konkurentsiohutu (concurrency-safe).
• Lukustatud aruandeperioodid lükkavad tagasi kõik kanded, mille kuupäev jääb selle sisse (409).
• Pehmelt kustutatud (soft-deleted) dokumendid säilitavad oma auditeerimisjälje; välja antud või registreeritud dokumente ei saa kustutada.