API reglur

Uppbygging beiðni

Allar aðgerðir eru í stíl við RPC og nota POST:

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

Kerfishlutar (modules): reference, partners, catalog, sales, purchases, ledger, bank, declarations, files, webhooks, audit. Aðgerðir (actions) eru sagnir: create, get, update, delete, list, auk sérhæfðra aðgerða eins og issue, register, match, apply-advance, generate.

Auðkenning og heimildir

Authorization: Bearer <api key>. Lyklar innihalda heimildir (scopes) sem bornar eru saman við hverja aðgerð:

• {module}:read - fyrir sækja/lista aðgerðir
• {module}:write - fyrir breytingar
• {module}:* eða * - almennir táknlistar (wildcards)

Vantar heimild -> 403 forbidden. Lykill vantar eða er ógildur -> 401 unauthorized.

Listafyrirspurnir

Allar list aðgerðir deila sömu forskrift:

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

Síunarvirkjar (filter operators): eq (jafnt og), ne (ekki jafnt og), contains (textaleit sem gerir ekki grein for stórum og litlum stöfum, eingöngu fyrir textareiti), gte (stærra en eða jafnt og), lte (minna en eða jafnt og), in (hvaða gildi sem er af allt að 500 gildum í lista). Reitir sem hægt er að raða eftir og síja eru skráðir á hvítlista fyrir hvern endapunkt (sjá OpenAPI forskriftina); óþekktir reitir skila villunni 400. Bættu totals: ["field", …] við beiðnina til að leggja saman tölulega reiti yfir allar fylgjandi raðir; þegar færslur tilheyra gjaldmiðli skilar totalsByCurrency sömu summum skiptum eftir gjaldmiðlakóða. Svör: { rows, total, page, pageSize, totals?, totalsByCurrency? }.

Peningar og dagsetningar

Fjárhæðir eru tugabrotstrengir með allt að 4 aukastöfum ("121.0000"), aldrei fleytitölur (floats). VSK er reiknaður í hverri línu með ávísum upp á næstu tölu (half-up rounding). Dagsetningar eru á sniðinu YYYY-MM-DD; tímatimplar eru á ISO 8601 UTC sniði.

Villur

Ein umbúðarskrá alls staðar:

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

Kóðar: validation (400/422, og 413 þegar upphalað skjal eða beiðnigeymsla er of stór), unauthorized (401), payment_required (402, prufutímabili eða fyrirframgreiddu innefti er lokið; skilaboðin útskýra hvernig halda skal áfram), forbidden (403), not_found (404), conflict (409), idempotency_key_reuse (422), idempotency_in_progress (409), rate_limited (429), internal (5xx). Þegar skilaboðin eru föst skilaboð gefur key þeim nafn svo forrit geti birt sína eigin þýðingu og params geymir gildin sem eiga að vera í þeim (til dæmis { "period": "2026-09" } fyrir læst uppgjörstímabil). Láttu requestId fylgja með þegar tilkynnt er um vandamál.

Tvíverkunarvarnir (Idempotency)

Bættu Idempotency-Key: <hvaða strengur sem er ≤255 stafir> við hvaða breytingarbeiðni sem er:

• Reyndu aftur með sama lykli og gögnum -> geymda svarið er endurtekið bæti fyrir bæti ásamt x-idempotent-replay: true.
• Sama lykil, önnur gögn -> 422 idempotency_key_reuse.
• Samtímis tvítekning á meðan sú fyrsta er í vinnslu -> 409 idempotency_in_progress.
• Lyklar heyra undir þann API lykil eða notanda sem sendir þá, innan þess fyrirtækis sem beiðnin á við um, þannig að tvær samþættingar eins fyrirtækis geta notað sama lykil. Beiðnir sem gerðar eru áður en fyrirtæki er til og account/* beiðnir halda lyklum per notanda, þannig að ítrekuð account/companies/create beiðni stofnar eitt fyrirtæki.
• Geymt svar er aðeins skilað eftir að kallaðili hefur staðist sömu heimildarathuganir aftur (heimild, hlutverk, fyrirtæki og greiðslustaða); annars fær beiðnin núverandi villu.
• Lyklar renna út eftir 24 klukkustundir. Villusvör (4xx) eru einnig endurtekin; 5xx svör eru ekki geymd þannig að ítrekanir keyrast upp á nýtt.

Takmarkanir á tíðni (Rate limits)

300 beiðnir á mínútu per API lykil (miðað við framvísað skilríki; beiðnir án auðkenningar eru takmarkaðar per IP-tölu). Virtu retry-after hausinn ef 429 villa kemur upp. x-ratelimit-* hausar sýna stöðu fjárhagsáætlunar þinnar.

Vefboð (Webhooks)

Atburðir eru skrifaðir í færsluvinnslubiðröð (transactional outbox) í sömu gagnagrunnsfærslu og breytingin - skjali sem hefur verið rúllað til baka er aldrei fylgt eftir með atburði og enginn atburður glatast. Afhendingar:

• POST beiðni á þína slóð með JSON atburðinum
• x-nordlet-timestamp: <unix sekúndur>, tíminn sem afhendingin var undirrituð
• x-nordlet-signature-v2: t=<tímatimbur>,v1=<hex HMAC-SHA256 af "<tímatimbur>.<hrátt efni>"> með því að nota áskriftarleyndarmálið þitt
• x-nordlet-signature: sha256=<hex HMAC-SHA256 af hráu efni>, haldið óbreyttu fyrir núverandi móttakendur
• x-nordlet-delivery inniheldur auðkenni afhendingar, það sama við hverja ítrekun á einni afhendingu
• Ekki-2xx svar eða tilvísun (redirect) er endrttekið eftir 30 sekúndur, 2 mínútur, 10 mínútur, 30 mínútur, 1 klukkustund, 3 klukkustundir, 6 klukkustundir og 12 klukkustundir, samtals í um 24 klukkustundir, áður en afhendingin er merkt sem mistök
• Hver afhending er send af einum netþjón í einu, þannig aðkeyrsla á nokkrum API tilvikum sendir hana ekki tvisvar

Staðfestu x-nordlet-signature-v2 með tíma-óbreytanlegum samanburði (constant-time comparison) áður en þú treystir gögnunum og hafnaðu afhendingu þar sem tímatimburinn er meira en 5 mínútum frá klukkunni þinni. Tímatimburinn er hluti af undirrituðum texta, þannig að ekki er hægt að endurtaka fangaða afhendingu síðar með nýjum tímatimbri. Geymdu x-nordlet-delivery auðkenni sem þú hefur unnið úr til að hunsa endurtekningu innan þess glugga. Hægt er að senda mistakta afhendingu aftur með webhooks/deliveries/redeliver.

Endurskoðunarslóð (Audit)

Hver breyting er skráð (actor, action, entity, diff) og hægt að leita í gegnum audit/list.

Bókhaldslegar tryggingar

• Færslubókfærslur eru jafnar - framfylgt af frestuðum gagnagrunnsgildru við staðfestingu (commit), ekki bara í forritkóða.
• Skjalsnúmer eru án bils per röð/ár; úthlutun er samsetningarörugg (concurrency-safe).
• Læst uppgjörstímabil hafna öllum færslum sem dagssettar eru innan þeirra (409).
• Músin-eydd (soft-deleted) skjöl halda endurskoðunarslóð sinni; ekki er hægt að eyða útgefnum/skráðum skjölum.