Konvencije API-ja

Oblik zahtjeva

Svaka operacija je POST poziv u RPC stilu:

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

Moduli: reference, partners, catalog, sales, purchases, ledger, bank, declarations, files, webhooks, audit. Akcije su glagoli: create, get, update, delete, list, uz domenske akcije kao što su issue, register, match, apply-advance, generate.

Autentifikacija i ovlaštenja

Authorization: Bearer <api key>. Ključevi nose ovlaštenja (scopes) koja se provjeravaju za svaku akciju:

• {module}:read - akcije dohvaćanja i izlistavanja (get/list)
• {module}:write - izmjene (mutations)
• {module}:* ili * - zamjenski znakovi (wildcards)

Nedostaje ovlaštenje -> 403 forbidden. Nedostaje ključ ili je nevažeći -> 401 unauthorized.

Upiti za popise

Sve list akcije dijele isti ugovor:

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

Operatori filtriranja: eq (jednako), ne (nije jednako), contains (pretraživanje teksta neovisno o veličini slova, samo za tekstualna polja), gte (veće ili jednako), lte (manje ili jednako), in (bilo koja vrijednost s popisa do najviše 500 vrijednosti). Polja po kojima se može sortirati i filtrirati definirana su bijelom listom (whitelisted) za svaku krajnju točku (pogledajte OpenAPI specifikaciju); nepoznata polja vraćaju pogrešku 400. Dodajte totals: ["field", …] u zahtjev za zbrajanje numeričkih polja kroz sve retke koji odgovaraju uvjetu; kada zapisi sadrže valutu, totalsByCurrency daje iste zbrojeve raspršene po oznaci valute. Odgovori: { rows, total, page, pageSize, totals?, totalsByCurrency? }.

Novčani iznosi i datumi

Novčani iznosi su decimalni nizovi znakova (strings) s najviše 4 decimalna mjesta ("121.0000") - nikada decimalni brojevi s pomičnim zarezom (floats). PDV se obračunava po stavki uz zaokruživanje na višu vrijednost na polovici (half-up rounding). Datumi su u formatu YYYY-MM-DD; vremenske oznake (timestamps) su u ISO 8601 UTC formatu.

Pogreške

Jedinstvena ovojnica svugdje:

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

Kodovi: validation (400/422, te 413 kada je prenesena datoteka ili tijelo zahtjeva preveliko), unauthorized (401), payment_required (402, probno razdoblje ili pretplaćeni kredit je istekao; poruka navodi kako nastaviti), forbidden (403), not_found (404), conflict (409), idempotency_key_reuse (422), idempotency_in_progress (409), rate_limited (429), internal (5xx). Kada je poruka jedna od fiksnih poruka, key ju imenuje kako bi klijent mogao prikazati vlastiti prijevod, a params sadrži vrijednosti koje ulaze u nju (na primjer { "period": "2026-09" } za zaključano računsko razdoblje). Uključite requestId prilikom prijavljivanja problema.

Idempotencija

Dodajte Idempotency-Key: <bilo koji niz znakova ≤255 znakova> svakom pozivu koji vrši izmjene:

• Ponovni pokušaj s istim ključem i podatcima (payload) -> pohranjeni odgovor se reproducira bajt po bajt uz zaglavlje x-idempotent-replay: true.
• Isti ključ, drukčiji podatci -> 422 idempotency_key_reuse.
• Istovremeni dvostruki poziv dok je prvi u tijeku -> 409 idempotency_in_progress.
• Ključevi pripadaju API ključu ili korisniku koji ih šalje, unutar tvrtke za koju se poziv izvršava, tako da dvije integracije jedne tvrtke mogu koristiti isti ključ. Pozivi izvršeni prije nego što tvrtka postoji, kao i pozivi account/*, čuvaju ključ po korisniku, pa ponovljeni poziv account/companies/create stvara jednu tvrtku.
• Pohranjeni odgovor vraća se tek nakon što pozivatelj ponovno prođe provjere dozvola (ovlaštenje, uloga, tvrtka i status naplate); u suprotnom poziv dobiva trenutnu pogrešku.
• Ključevi istječu nakon 24 sata. Odgovori s pogreškom (4xx) se također reproduciraju; odgovori s kodom 5xx se ne pohranjuju kako bi ponovljeni pokušaji ponovno izvršili radnju.

Ograničenja broja zahtjeva (Rate limits)

300 zahtjeva u minuti po API ključu (po predloženim vjerodajnicama; neautentificirani zahtjevi ograničeni su po IP adresi). Kod odgovora 429, poštujte zaglavlje retry-after. Zaglavlja x-ratelimit-* izvještavaju o vašem preostalom budžetu.

Webhooks

Događaji se zapisuju u transakcijsku odlaznu bilježnicu (outbox) unutar iste bazične transakcije kao i promjena - dokument čija je transakcija poništena nikada ne odašilje događaj, a niti jedan događaj nije izgubljen. Isporuke:

• POST zahtjev na vaš URL s JSON-om događaja
• x-nordlet-timestamp: <unix sekunde>, vrijeme kada je isporuka potpisana
• x-nordlet-signature-v2: t=<timestamp>,v1=<hex HMAC-SHA256 od "<timestamp>.<raw body>"> korištenjem tajnog ključa vaše pretplate
• x-nordlet-signature: sha256=<hex HMAC-SHA256 sirovog tijela>, ostavljeno nepromijenjeno za postojeće primatelje
• x-nordlet-delivery nosi ID isporuke, koji je isti kod svakog ponovnog pokušaja jedne isporuke
• Odgovor koji nije u rasponu 2xx ili preusmjeravanje ponovno se pokušava nakon 30 sekundi, 2 minute, 10 minuta, 30 minuta, 1 sat, 3 sata, 6 sati i 12 sati, otprilike 24 sata ukupno, prije nego što se isporuka označi neuspješnom
• Svaku isporuku šalje jedan poslužitelj u isto vrijeme, tako da pokretanje nekoliko API instanci neće uzrokovati dvostruko slanje

Provjerite x-nordlet-signature-v2 usporedbom koja traje konstantno vrijeme (constant-time comparison) prije nego što date povjerenje podatcima, i odbacite isporuku čija je vremenska oznaka udaljenija od vašeg sata više od 5 minuta. Vremenska oznaka dio je potpisanog teksta, tako da se presretnuta isporuka ne može kasnije ponovno reproducirati s novom vremenskom oznakom. Pohranite ID-jeve x-nordlet-delivery koje ste obradili kako biste zanemarili ponovni unos unutar tog vremenskog prozora. Neuspjela isporuka može se ponovno poslati putem webhooks/deliveries/redeliver.

Revizija (Audit)

Svaka promjena se bilježi (actor, action, entity, diff) i može se pretraživati putem audit/list.

Računovodstvena jamstva

• Knjiženja u dnevniku su uravnotežena - to se provodi odgođenim okidačem baze podataka (database trigger) u trenutku potvrde (commit), a ne samo logikom aplikacije.
• Brojevi dokumenata nemaju praznina po seriji/godini; dodjela je sigurna od istovremenog izvođenja (concurrency-safe).
• Zaključana računovodstvena razdoblja odbacuju svako knjiženje datirano unutar njih (409).
• Logično obrisani dokumenti zadržavaju svoju revizijsku stazu; izdani/registrirani dokumenti ne mogu se brisati.