Konvencie API

Štruktúra požiadaviek

Každá operácia je v štýle RPC volania metódou POST:

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

Moduly: reference, partners, catalog, sales, purchases, ledger, bank, declarations, files, webhooks, audit. Akcie sú slovesá: create, get, update, delete, list plus špecifické akcie domény ako issue, register, match, apply-advance, generate.

Autentifikácia a rozsahy (scopes)

Authorization: Bearer <api key>. Kľúče obsahujú rozsahy oprávnení overované pri každej akcii:

• {module}:read - akcie na získanie/zoznam
• {module}:write - zmeny a zápisy
• {module}:* alebo * - zástupné znaky (wildcards)

Chýbajúci rozsah vedie k chybovému kódu 403 forbidden. Chýbajúci alebo neplatný kľúč vedie k chybovému kódu 401 unauthorized.

Zoznamové dopyty

Všetky akcie typu list zdieľajú rovnakú štruktúru:

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

Operátory filtrov: eq (rovná sa), ne (nerovná sa), contains (zhoda textu bez ohľadu na veľkosť písmen, iba pre textové políčka), gte (väčšie alebo rovné), lte (menšie alebo rovné), in (ľubovoľná hodnota zo zoznamu obsahujúceho najviac 500 hodnôt). Políčka, podľa ktorých možno radiť a filtrovať, sú preddefinované na základe whitelistu pre každý koncový bod (pozrite si špecifikáciu OpenAPI); neznáme políčka vrátia chybu 400. Pridaním parametra totals: ["field", …] do požiadavky získate súčet číselných polí pre všetky zodpovedajúce riadky; ak záznamy obsahujú menu, políčko totalsByCurrency poskytuje rovnaké súčty rozdelené podľa kódov mien. Odpovede: { rows, total, page, pageSize, totals?, totalsByCurrency? }.

Peňažné sumy a dátumy

Peňažné hodnoty sú desatinné reťazce s najviac 4 desatinnými miestami ("121.0000"), nikdy nie desatinné čísla s plávacou rádovou čiarkou (floats). DPH sa počítava pre každý riadok osobitne so zaokrúhľovaním nahor pri polovičnej hodnote (half-up rounding). Dátumy majú formát YYYY-MM-DD; časové značky (timestamps) sú v UTC formáte podľa normy ISO 8601.

Chyby

Všade sa používa jednotná obálka:

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

Kódy: validation (400/422 a 413, ak je odovzdaný súbor alebo telo požiadavky príliš veľké), unauthorized (401), payment_required (402, skúšobné obdobie alebo predplatený kredit vypršal; správa informuje, ako pokračovať), forbidden (403), not_found (404), conflict (409), idempotency_key_reuse (422), idempotency_in_progress (409), rate_limited (429), internal (5xx). Ak je správa jednou z pevných chybových hlásení, políčko key ju identifikuje, aby klient mohol zobraziť vlastný preklad, a políčko params obsahuje hodnoty, ktoré sa do nej dosadia (napríklad { "period": "2026-09" } pre uzatvorené účtovné obdobie). Pri hlásení problémov vždy uveďte identifikátor requestId.

Idempotencia

Pridajte hlavičku Idempotency-Key: <ľubovoľný reťazec ≤255 znakov> do každej mutujúcej požiadavky:

• Opakované volanie s rovnakým kľúčom a payloadom - uložená odpoveď sa pre prehrá presne v pôvodnom znení bajt po bajte s hlavičkou x-idempotent-replay: true.
• Rovnaký kľúč, odlišný payload - chyba 422 idempotency_key_reuse.
• Súbežná duplicitná požiadavka, zatiaľ čo prvá sa ešte spracováva - chyba 409 idempotency_in_progress.
• Kľúče patria k API kľúču alebo používateľovi, ktorý ich odosiela, v rámci spoločnosti, pre ktorú sa volanie vykonáva, takže dve integrácie jednej spoločnosti môžu použiť rovnaký kľúč. Volania uskutočnené pred vznikom spoločnosti a volania account/* uchovávajú kľúče pre každého používateľa, takže opakované volanie account/companies/create vytvorí iba jednu spoločnosť.
• Uložená odpoveď sa vráti až vtedy, keď volajúci opätovne úspešne prejde kontrolami oprávnení (rozsah, rola, spoločnosť a stav fakturácie); v opačnom prípade volanie dostane aktuálnu chybovú odpoveď.
• Kľúče vypršia po 24 hodinách. Chybové odpovede (4xx) sa prehrávajú tiež; odpovede 5xx sa neukladajú, takže opakované pokusy sa zopakujú nanovo.

Limity požiadaviek (Rate limits)

300 požiadaviek za minútu na jeden API kľúč (na predložené poverenie; neautentifikované požiadavky sú obmedzené na základe IP adresy). Pri chybovom kóde 429 rešpektujte hlavičku retry-after. Hlavičky x-ratelimit-* informujú o stave vášho limitu.

Webhooky

Udalosti sa zapisujú do transakčnej schránky (transactional outbox) v rámci tej istej databázovej transakcie ako samotná zmena - vrátená (rolled-back) transakcia nikdy nevygeneruje udalosť a žiadna udalosť sa nestratí. Doručovanie:

• POST požiadavka na vašu URL adresu s JSON objektom udalosti
• x-nordlet-timestamp: <unix sekundy>, čas, kedy bolo doručenie podpísané
• x-nordlet-signature-v2: t=<timestamp>,v1=<hexadecimálny HMAC-SHA256 reťazec pre "<timestamp>.<surový payload>"> za použitia tajného kľúča vašej predplatenej služby
• x-nordlet-signature: sha256=<hexadecimálny HMAC-SHA256 reťazec surového payloadu>, zachované v nezmenenej podobe pre existujúcich príjemcov
• x-nordlet-delivery obsahuje ID doručenia, ktoré je rovnaké pri každom opakovanom pokuse o to isté doručenie
• Odpoveď iná ako 2xx alebo presmerovanie sa opätovne pokúsi doručiť po 30 sekundách, 2 minútach, 10 minútach, 30 minútach, 1 hodine, 3 hodinách, 6 hodinách a 12 hodinách (približne po 24 hodinách celkovo), predtým než sa doručenie označí ako zlyhané
• Každé doručenie odosiela vždy iba jeden server, takže prevádzka viacerých inštancií API nespôsobí duplicitné odoslanie

Pred dôverou v obsah payloadu overte podpis x-nordlet-signature-v2 porovnaním odolným voči časovým útokom (constant-time comparison) a odmietnite doručenie, ktorého časová značka sa líši od hodín vášho servera o viac ako 5 minút. Časová značka je súčasťou podpísaného textu, takže zachytené doručenie nemožno neskôr prehrať s novou časovou značkou. Ukladajte si spracované ID z hlavičky x-nordlet-delivery, aby ste ignorovali prípadné duplicitné doručenia v danom časovom okne. Zlyhané doručenie je možné odoslať znova pomocou koncového bodu webhooks/deliveries/redeliver.

Audit

Každá zmena sa zaznamenáva (actor, action, entity, diff) a dá sa vyhľadávať prostredníctvom audit/list.

Účtovné záruky

• Účtovné zápisy sú vždy vyrovnané (balanced) - vynucuje sa to odloženým databázovým triggrom v okamihu potvrdenia transakcie (commit), nielen aplikačným kódom.
• Čísla dokladov sú bez medzier v rámci číselného radu a roka; prideľovanie čísel je bezpečné voči súbežným zápisom (concurrency-safe).
• Uzatvorené účtovné obdobia odmietnu akýkoľvek zápis s dátumom spadajúcim do tohto obdobia (409).
• Mäkko zmazané doklady (soft-deleted) si zachovávajú svoju históriu auditu; vystavené alebo zaevidované doklady nie je možné vymazať.