API konvenciók

Kérések felépítése

Minden művelet egy RPC stílusú POST kérés:

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

Modulok: reference, partners, catalog, sales, purchases, ledger, bank, declarations, files, webhooks, audit. A műveletek (action) igék: create, get, update, delete, list, valamint domainműveletek, mint az issue, register, match, apply-advance, generate.

Hitelesítés és jogosultsági körök

Authorization: Bearer <api key>. A kulcsok műveletenként ellenőrzött jogosultsági köröket (scope) tartalmaznak:

• {module}:read - olvasási/listázási műveletek
• {module}:write - módosítások
• {module}:* vagy * - helyettesítő karaktersorok (wildcard)

Hiányzó jogosultsági kör esetén 403 forbidden (tiltva). Hiányzó vagy érvénytelen kulcs esetén 401 unauthorized (jogosulatlan).

Listázási lekérdezések

Minden list művelet ugyanazt a szerződést követi:

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

Szűrési operátorok: eq (egyenlő), ne (nem egyenlő), contains (kis- és nagybetűre nem érzékeny szövegegyezés, csak szöveges mezőknél), gte (nagyobb vagy egyenlő), lte (kisebb vagy egyenlő), in (legfeljebb 500 értéket tartalmazó lista bármely eleme). A rendezhető és szűrhető mezők végpontokonként fehérlistán szerepelnek (lásd az OpenAPI specifikációt); ismeretlen mezők esetén a rendszer 400-as hibát ad vissza. Ha hozzáadja a totals: ["field", …] paramétert a kéréshez, a rendszer összeadja a numerikus mezőket az összes illeszkedő sorra; ha a rekordokhoz tartozik pénznem, a totalsByCurrency ugyanezeket az összegeket pénznemkódok szerint lebontva adja vissza. Válaszok: { rows, total, page, pageSize, totals?, totalsByCurrency? }.

Pénzösszegek és dátumok

A pénzösszegek legfeljebb 4 tizedesjegyű decimális karakterláncok ("121.0000"), soha nem lebegőpontos számok. Az áfát soronként számítják ki felfelé kerekítéssel (half-up rounding). A dátumok formátuma YYYY-MM-DD; az időbélyegek ISO 8601 UTC formátumúak.

Hibák

Mindenhol egyetlen hibaléptető (envelope) szerepel:

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

Kódok: validation (400/422, valamint 413, ha a feltöltött fájl vagy a kérés törzse túl nagy), unauthorized (401), payment_required (402, a próbaidőszak vagy az előre fizetett keret lejárt; az üzenet tartalmazza a folytatás módját), forbidden (403), not_found (404), conflict (409), idempotency_key_reuse (422), idempotency_in_progress (409), rate_limited (429), internal (5xx). Ha az üzenet egy a rögzített üzenetek közül, a key megnevezi azt, hogy a kliens megjeleníthesse a saját fordítását, a params pedig tartalmazza a belekerülő értékeket (például { "period": "2026-09" } egy lezárt könyvelési időszak esetén). Problémák bejelentésekor kérjük, adja meg a requestId azonosítót is.

Idempotencia

Adja hozzá az Idempotency-Key: <bármilyen karakterlánc ≤255 karakter> fejet bármely módosító híváshoz:

• Újrapróbálás ugyanazzal a kulccsal és adattartalommal: a tárolt választ a rendszer bájtról bájtra visszajátssza az x-idempotent-replay: true fejléccel.
• Ugyanez a kulcs, eltérő adattartalom: 422 idempotency_key_reuse.
• Egyidejű duplikáció, amíg az első kérés még folyamatban van: 409 idempotency_in_progress.
• A kulcsok ahhoz az API-kulcshoz vagy felhasználóhoz tartoznak, amely elküldi őket, azon a cégen belül, amelynek nevében a hívás történik, így egy cég két integrációja használhatja ugyanazt a kulcsot. A cég létrejötte előtt indított hívások, valamint az account/* hívások felhasználonként tartják meg a kulcsokat, így egy megismételt account/companies/create hívás csak egy céget hoz létre.
• A tárolt választ a rendszer csak azután adja vissza, hogy a hívó ismét átment a jogosultság-ellenőrzéseken (jogosultsági kör, szerepkör, cég- és számlázási státusz); ellenkező esetben a hívás az aktuális hibát kapja.
• A kulcsok 24 óra elteltével lejárnak. A hibaelemet tartalmazó válaszokat (4xx) a rendszer szintén visszajátssza; az 5xx válaszokat nem tárolja, így az újrapróbálkozások újraeutják a műveletet.

Sebességkorlátok

API-kulcsonként 300 kérés/perc (a bemutatott hitelesítő adat alapján; a hitelesítés nélküli kérések IP-cím alapján vannak korlátozva). 429-es hiba esetén tartsa tiszteletben a retry-after fejet. Az x-ratelimit-* fejek számolnak be a keretéről.

Webhookok

Az események egy tranzakciós kimenő üzenetsorba (outbox) kerülnek, ugyanabban az adatbázis-tranzakcióban, mint a változás, így a visszagurított dokumentum soha nem bocsát ki eseményt, és egyetlen esemény sem vész el. Kézbesítés:

• POST kérés az Ön URL-címére az esemény JSON adataival
• x-nordlet-timestamp: <unix seconds>, a kézbesítés aláírásának időpontja
• x-nordlet-signature-v2: t=<timestamp>,v1=<a "<timestamp>.<raw body>" hexadecimális HMAC-SHA256 értéke> az előfizetési titkos kulcs felhasználásával
• x-nordlet-signature: sha256=<a nyers törzs hexadecimális HMAC-SHA256 értéke>, a meglévő fogadók számára változatlanul megőrizve
• x-nordlet-delivery tartalmazza a kézbesítés azonosítóját, amely egy adott kézbesítés minden újrapróbálásakor azonos marad
• A nem 2xx válasz vagy az átirányítás után a rendszer 30 másodperc, 2 perc, 10 perc, 30 perc, 1 óra, 3 óra, 6 óra és 12 óra múlva próbálkozik újra (összesen mintegy 24 órán keresztül), mielőtt a kézbesítést sikertelennek jelölné
• Minden kézbesítést egyszerre csak egy szerver küld el, így több API-példány futtatása sem küldi el kétszer

Mielőtt megbízna az adattartalomban, ellenőrizze az x-nordlet-signature-v2 értéket egy időállandó összehasonlítással, és utasítsa el azt a kézbesítést, amelynek időbélyege több mint 5 perccel eltér az órájától. Az időbélyeg az aláírt szöveg része, így a rögzített kézbesítést nem lehet később új időbélyeggel visszajátszani. A feldolgozott x-nordlet-delivery azonosítókat tárolja el, hogy az adott ablakon belül figyelmen kívül thesse az ismétléseket. A sikertelen kézbesítés a webhooks/deliveries/redeliver végponttal újra elküldhető.

Audit

Minden módosítás rögzítésre kerül (actor, action, entity, diff), és lekérdezhető az audit/list végponton keresztül.

Könyvelési garanciák

• A naplóbejegyzések egyensúlyban vannak - ezt a kód mellett egy, a véglegesítés (commit) időpontjában lefutó, halasztott adatbázis-trigger kényszeríti ki.
• A bizonylatszámok sorozatonként/évenként hiánytalanok; a kiosztás konkurens módon biztonságos.
• A lezárt könyvelési időszakok elutasítanak minden olyan könyvelést, amelynek dátuma ezekbe esik (409).
• A logikailag törölt (soft-deleted) dokumentumok megőrzik az auditnaplójukat; a kiállított/regisztrált dokumentumok nem törölhetők.