Konvenzjonijiet tal-API

Struttura tat-talbiet

Kull operazzjoni hija POST stil RPC:

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

Moduli: reference, partners, catalog, sales, purchases, ledger, bank, declarations, files, webhooks, audit. L-azzjonijiet huma verbi: create, get, update, delete, list, flimkien ma' azzjonijiet tad-dominju bħal issue, register, match, apply-advance, generate.

Awtentikazzjoni u ambiti

Authorization: Bearer <api key>. Iċ-wievet iġorru ambiti (scopes) li jiġu vverifikati għal kull azzjoni:

• {module}:read - azzjonijiet ta' qari/lista
• {module}:write - mutazzjonijiet
• {module}:* jew * - wildcards

Ambitu neqsin iwassal għal 403 forbidden. Ċavetta neqsin jew invalida twassal għal 401 unauthorized.

Listi ta' mistoqsijiet

L-azzjonijiet list kollha jaqsmu kuntratt wieħed:

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

Operaturi tal-filtru: eq (ugwali), ne (mhux ugwali), contains (tqabbil tat-test li ma jiddistingwix bejn it-tip ta' ittri, oqsma tat-test biss), gte (ikbar minn jew ugwali), lte (iżgħar minn jew ugwali), in (kwalunkwe waħda minn lista ta' sa 500 valur). L-oqsma li jistgħu jiġu ssordjati u ffiltrati huma inklużi f'lista abjad (whitelisted) għal kull punt tat-tmiem (ara l-ispeċifikazzjoni tal-OpenAPI); oqsma mhux magħrufa jirritornaw 400. Żid totals: ["field", …] mat-talba biex tgħodd l-oqsma numeriċi fuq kull ringiela li taqbel; meta r-reġistrazzjonijiet ikollhom munita, totalsByCurrency jagħti l-istess somom maqsuma skont il-kodiċi tal-munita. Risposti: { rows, total, page, pageSize, totals?, totalsByCurrency? }.

Flus u dati

Il-valuri monetarji huma string ta' deċimali b'sa 4 postijiet deċimali ("121.0000") - qatt ma huma floats. Il-VAT tiġi kkalkulata għal kull linja b'tundir għall-eqreb nofs ('half-up rounding'). Id-dati huma fil-format YYYY-MM-DD; it-timpamps huma f'ISO 8601 UTC.

Żbalji

Pakkett wieħed kullimkien:

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

Kodiċijiet: validation (400/422, u 413 meta fajl imtella' jew il-korp tat-talba huwa kbir wisq), unauthorized (401), payment_required (402, il-perjodu ta' prova jew il-kreditu mħallas minn qabel skada; il-messaġġ jispjega kif għandek tkompli), forbidden (403), not_found (404), conflict (409), idempotency_key_reuse (422), idempotency_in_progress (409), rate_limited (429), internal (5xx). Meta l-messaġġ huwa wieħed mill-messaġġi fissi, key isemmih sabiex klijent ik pueda juri t-traduzzjoni tiegħu stess, u params iżomm il-valuri li jmorru fih (pereżempju { "period": "2026-09" } għal perjodu ta' kontabilità msakkar). Inludi l-requestId meta tirrapporta problemi.

Idempotenza

Żid Idempotency-Key: <kwalunkwe string ≤255 karattru> ma' kwalunkwe sejħa ta' mutazzjoni:

• Erġa' pprova bl-istess ċavetta u payload - ir-rispons maħżun jintlagħab mill-ġdid byte b'byte b' x-idempotent-replay: true.
• L-istess ċavetta, payload differenti - 422 idempotency_key_reuse.
• Duplikat fl-istess ħin waqt li l-ewwel wieħed ikun qed jiġi pproċessat - 409 idempotency_in_progress.
• Iċ-wievet jappartjenu għaċ-ċavetta tal-API jew għall-utent li jibgħathom, fi ħdan il-kumpanija li għandha x'taqsam mas-sejħa, sabiex żewġ integrazzjonijiet ta' kumpanija waħda jkunu jistgħu jużaw l-istess ċavetta. Sejħiet magħmula qabel ma teżisti kumpanija, u sejħiet account/*, iżommu ċ-wievet għal kull utent, sabiex sejħa ripetuta account/companies/create toħloq kumpanija waħda.
• Rispons maħżun jiġi rritornat biss wara li min qed jsejjaħ jgħaddi mill-verifiki tal-permessi mill-ġdid (ambitu, rwol, kumpanija u status tal-fatturazzjoni); inkella s-sejħa tieħu l-iżball kurrenti.
• Iċ-wievet jiskadu wara 24 siegħa. Ir-risposti ta' żball (4xx) jintlagħbu mill-ġdid ukoll; ir-risposti 5xx ma jinħażnux sabiex l-ippruvaturi mill-ġdid jerġgħu jeżegwixxu.

Limiti tar-rata (Rate limits)

300 talba kull minuta għal kull ċavetta tal-API (għal kull kredenzjali ppreżentata; talbiet mhux awtentikati huma limitati għal kull IP). Fuq 429, irrispetta l-header retry-after. L-headers x-ratelimit-* jirrapportaw il-baġit tiegħek.

Webhooks

L-avvenimenti huma miktuba f'outbox transazzjonali fl-istess transazzjoni tad-database bħall-bidla - dokument irriversjat qatt ma joħroġ avveniment, u l-ebda avveniment ma jintilef. Kunsinni:

• POST lejn l-URL tiegħek bl-avveniment JSON
• x-nordlet-timestamp: <sekondi unix>, il-ħin li fih ġiet iffirmata l-kunsinna
• x-nordlet-signature-v2: t=<timestamp>,v1=<hex HMAC-SHA256 ta' "<timestamp>.<raw body>"> bl-użu tas-sigriet tas-sabonament tiegħek
• x-nordlet-signature: sha256=<hex HMAC-SHA256 tal-korp mhux ipproċessat>, miżmum bla bidla għal riċevituri eżistenti
• x-nordlet-delivery iġorr l-id tal-kunsinna, l-istess f'kull tentattiv mill-ġdid ta' kunsinna waħda
• Tweġiba li mhix 2xx jew ridirezzjoni terġa' tiġi ppruvata wara 30 sekonda, 2 minuti, 10 minuti, 30 minuta, siegħa, 3 sigħat, 6 sigħat u 12-il siegħa, madwar 24 siegħa b'kollox, qabel ma l-kunsinna tiġi mmarkata bħala falluta
• Kull kunsinna tintbagħat minn server wieħed kull darba, sabiex it-tħaddim ta' diversi istanzi tal-API ma jibgħathiex darbtejn

Ivvrika x-nordlet-signature-v2 b'paragun f'ħin kostanti qabel ma tafda l-payload, u jirrifjuta kunsinna li t-timpamp tagħha jkun aktar minn 5 minuti 'l bogħod mill-arloġġ tiegħek. It-timpamp huwa parti mit-test iffirmat, sabiex kunsinna qabda ma tistax tintlagħab mill-ġdid aktar tard bi timpamp frisk. Aħżen l-ids ta' x-nordlet-delivery li pproċessajt biex tinjora ripetizzjoni f'dak il-perjodu. Kunsinna falluta tista' tintbagħat mill-ġdid bi webhooks/deliveries/redeliver.

Awditjar

Kull mutazzjoni tiġi rreġistrata (actor, action, entity, diff) u tista' tiġi mistoqsija permezz ta' audit/list.

Garanziji tal-kontabilità

• Il-postings tal-ġurnal huma bbilanċjati - infurzati minn trigger tad-database pospost fil-ħin tal-kommit, mhux biss b'kodiċi tal-applikazzjoni.
• In-numri tad-dokumenti m'għandhomx lakuni għal kull serje/sena; l-allokazzjoni hija sigura għall-konkorrenza.
• Perjodi ta' kontabilità msakkra jirrifjutaw kwalunkwe posting datat fihom (409).
• Dokumenti mħassra b'mod artab iżommu l-binarju tal-awditjar tagħhom; dokumenti maħruġa/reġistrati ma jistgħux jitħassru.