API susitarimai

Užklausų struktūra

Kiekviena operacija yra RPC stiliaus POST užklausa:

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

Moduliai: reference, partners, catalog, sales, purchases, ledger, bank, declarations, files, webhooks, audit. Veiksmai (actions) yra veiksmažodžiai: create, get, update, delete, list, taip pat specifiniai domeno veiksmai, tokie kaip issue, register, match, apply-advance, generate.

Autentifikacija ir prieigos sritys

Authorization: Bearer <api key>. Raktai turi prieigos sritis (scopes), kurios tikrinamos kiekvienam veiksmui:

• {module}:read — gavimo ir sąrašų (get / list) veiksmai
• {module}:write — duomenų keitimo veiksmai
• {module}:* arba * — visų teisių (wildcard) simboliai

Trūksta prieigos srities → 403 forbidden. Trūksta rakto arba jis neteisingas → 401 unauthorized.

Sąrašų užklausos

Visiems sąrašų (list) veiksmams taikomas vienodas formatas:

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

Filtravimo operatoriai: eq, neq, gt, gte, lt, lte, like, in. Laukai, pagal kuriuos galima rikiuoti ir filtruoti, yra griežtai apibrėžti kiekvienam galiniam taškui (endpoint) atskirai (žr. OpenAPI specifikaciją); nurodžius nežinomus laukus grąžinama 400 klaida. Atsakymų struktūra: { rows, total, page, pageSize }.

Pinigai ir datos

Piniginės vertės pateikiamos kaip dešimtainės trupmenos teksto formatu su ne daugiau kaip 4 skaitmenimis po kablelio ("121.0000") — niekada nenaudokite slankiojo kablelio (float) tipo. PVM skaičiuojamas kiekvienai eilutei atskirai, taikant apvalinimą pagal aritmetines taisykles („half-up“ apvalinimas). Datos nurodomos YYYY-MM-DD formatu; laiko žymos (timestamps) yra ISO 8601 UTC formatu.

Klaidos

Visur naudojamas vienodas struktūros apvalkalas:

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

Klaidų kodai: validation (400/422), unauthorized (401), forbidden (403), not_found (404), conflict (409), idempotency_key_reuse (422), idempotency_in_progress (409), rate_limited (429), internal (5xx). Pranešdami apie problemas, visada nurodykite requestId.

Idempotentiškumas

Į bet kokią duomenis keičiančią užklausą įtraukite Idempotency-Key: <any string ≤255 chars> antraštę:

• Pakartojus užklausą su tuo pačiu raktu ir duomenimis → išsaugotas atsakymas grąžinamas baitas į baitą kartu su antrašte x-idempotent-replay: true.
• Tas pats raktas, bet kiti duomenys → 422 idempotency_key_reuse.
• Vienalaikis dublikatas, kol pirmoji užklausa dar vykdoma → 409 idempotency_in_progress.
• Raktai nustoja galioti po 24 valandų. Klaidų atsakymai (4xx) taip pat atkuriami; 5xx atsakymai nėra išsaugomi, todėl kartojant jie vykdomi iš naujo.

Užklausų limitai

300 užklausų per minutę vienam API raktui (pagal pateiktus prisijungimo duomenis; neautentifikuotos užklausos ribojamos pagal IP adresą). Gavę 429 klaidą, vadovaukitės retry-after antraštės reikšme. x-ratelimit-* antraštės nurodo jūsų likusį limitų biudžetą.

Webhooks

Įvykiai (events) įrašomi į tranzakcinę siunčiamųjų dėžutę (transactional outbox) tos pačios duomenų bazės tranzakcijos metu kaip ir pats pakeitimas — atšauktas (rolled-back) dokumentas niekada nesugeneruos įvykio, o joks įvykis nebus prarastas. Pristatymas:

• POST užklausa į jūsų nurodytą URL su įvykio JSON duomenimis
• x-nordlet-signature: sha256=<hex HMAC-SHA256 of the raw body> naudojant jūsų prenumeratos paslaptį (subscription secret)
• Pakartotiniai bandymai taikant eksponentinį vėlinimą (exponential backoff) gavus atsakymus, kurių kodas nėra 2xx

Prieš pasitikėdami gautais duomenimis (payload), patikrinkite parašus naudodami pastovaus laiko palyginimą (constant-time comparison).

Auditas

Kiekvienas duomenų keitimas yra registruojamas (actor, action, entity, diff) ir jį galima užklausti per audit/list.

Apskaitos garantijos

• Didžiosios knygos įrašai yra subalansuoti — tai užtikrinama atidėtu duomenų bazės trigeriu patvirtinimo (commit) metu, o ne tik per aplikacijos kodą.
• Dokumentų numeriai serijoje / metuose priskiriami be tarpų; numerių priskyrimas yra saugus vienalaikiam vykdymui (concurrency-safe).
• Uždaryti apskaitos laikotarpiai atmeta bet kokį įrašą su data, patenkančia į šį laikotarpį (409 klaida).
• Logiškai ištrinti (soft-deleted) dokumentai išlaiko savo audito pėdsaką; išrašytų ar užregistruotų dokumentų ištrinti negalima.