Comhombáistí API

Cruth iarratais

Is oibríocht de chineál RPC agus POST í gach oibríocht:

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

Modúil: reference, partners, catalog, sales, purchases, ledger, bank, declarations, files, webhooks, audit. Is briathra iad na gníomhartha: create, get, update, delete, list, chomh maith le gníomhartha fearainne amhail issue, register, match, apply-advance, generate.

Fíordheimhniú agus scóip

Authorization: Bearer <api key>. Tá scóip ag baint leis na eochracha a seiceáiltear do gach gníomh:

• {module}:read - gníomhartha fála/liostaithe
• {module}:write - só-ghníomhartha (mutations)
• {module}:* nó * - Ilchártaí (wildcards)

Scóip ar ciet → 403 forbidden. Eochair ar ciet nó neamhbhailí → 401 unauthorized.

Cuardaigh liostaí

Comhroinneann gach gníomh list conradh amháin:

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

Oibreoirí scagtha: eq (cothrom le), ne (neamhchothrom le), contains (comhoiriúnություն téacs neamhíogair do cháslitreacha, réimsí téacs amháin), gte (níos mó ná nó cothrom le), lte (níos lú ná nó cothrom le), in (bann de liosta suas le 500 luach). Tá réimsí Sórtála agus Scagtha ceadaithe ar an ngeata API (féach ar shonraíocht OpenAPI); is cúis le 400 iad na réimsí anaithnide. Cuir totals: ["field", …] leis an iarratas chun luachanna uimhriúla a shuimiú thar gach ró comhoiriúnach; nuair a bhíonn airgeadra ag na taifid, tugann totalsByCurrency na suimanna céanna roinnte de réir cód airgeadra. Freagraí: { rows, total, page, pageSize, totals?, totalsByCurrency? }.

Airgeadraí agus dátaí

Is teaghráin deachúla iad luachanna airgeadaíochta le up to 4 áit dheachúlacha ("121.0000") - ní cuimilteoirí (floats) iad go deo. Ríomhtar CBL in aghaidh an líne le babhta leath-suas (half-up rounding). Is é YYYY-MM-DD format na ndátaí; is iad stampaí ama ná ISO 8601 UTC.

Earráidí

Clúdach amháin i ngach áit:

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

Cóid: validation (400/422, agus 413 nuair a bhíonn comhad uaslódáilte nó corp iarratais ró-mhór), unauthorized (401), payment_required (402, tá deireadh leis an triail nó leis an gcreidmheas réamhíoctha; cuireann an teachtaireacht in iúl conas leanúint ar aghaidh), forbidden (403), not_found (404), conflict (409), idempotency_key_reuse (422), idempotency_in_progress (409), rate_limited (429), internal (5xx). Nuair a bhíonn an teachtaireacht ar cheann de na teachtaireachtaí socraithe, ainmníonn key í ionas gur féidir le cliant a aistriúchán féin a thaispeáint, agus coinníonn params na luachanna a théann isteach ann (mar shampla { "period": "2026-09" } do thréimhse chuntasaíochta ghlasáilte). Cuir an requestId san áireamh agus fadhbanna á dtuairisciú agat.

Neamh-inathraitheacht (Idempotency)

Cuir Idempotency-Key: <any string ≤255 chars> le haon ghlao só-ghné (mutating call):

• Athsheol leis an eochair agus an t-ualach íocaíochta céanna - déantar an freagra stóráilte a athimirt beart ar bheart le x-idempotent-replay: true.
• An eochair chéanna, ualach íocaíochta difriúil → 422 idempotency_key_reuse.
• Dúblach comhuaineach agus an chéad cheann ar siúl → 409 idempotency_in_progress.
• Baineann na eochracha leis an eochair API nó leis an úsáideoir a sheolann iad, laistigh den chuideachta ar son a bhfeidhmíonn an glaodh, ionas gur féidir le dhá chomhtháthú d'aon chuideachta an eochair chéanna a úsáid. Coinníonn glaonna a dhéantar sula mbíonn cuideachta ann, agus glaonna account/*, eochracha in aghaidh an úsáideora, ionas gur féidir le glao athchleachtach account/companies/create cuideachta amháin a chruthú.
• Ní th қайrtear freagra stóráilte ach amháin tar éis don té a ghlaonn na seiceálacha ceada céanna a rís (scóip, ról, cuideachta agus stádas billeála); mura ndéantar, faigheann an glao an earráid reatha.
• Téann na eochracha in éag tar éis 24 uair an chloig. Déantar freagraí earráide (4xx) a athimirt freisin; ní stóráiltear freagraí 5xx ionas go n-athfheidhmítear athsheolta.

Teorainneacha ráta

300 iarratas/daite in aghaidh an eochair API (in aghaidh na dteastas curtha i láthair; tá teorainn le iarratais neamhfhíordheimhnithe in aghaidh an IP). Ar 429, tabhair ómós don cheanntásc retry-after. Tugann ceanntásc x-ratelimit-* tuairisc ar do bhuiséad.

Webhooks

Scríobhtar imeachtaí chuig as-bosca idirbheartach san idirbheart bunachar sonraí céanna leis an athrú - ní astaíonn doiciméad a rolladh ar ais a leithéid d'imeacht riamh, agus ní cailleann aon imeacht. Seachadtaí:

• POST chuig do URL leis an JSON imeachta
• x-nordlet-timestamp: <unix seconds>, an t-am a síníodh an seachadadh
• x-nordlet-signature-v2: t=<timestamp>,v1=<hex HMAC-SHA256 of "<timestamp>.<raw body>"> ag úsáid do rúin síntiúis
• x-nordlet-signature: sha256=<hex HMAC-SHA256 of the raw body>, coinnithe gan athrú do ghlacadóirí reatha
• Iompraíonn x-nordlet-delivery an ID seachadta, an ceann céanna ar gach athsheoladh d'aon seachadadh amháin
• Déantar freagra nach 2xx nó atreorú a athsheoladh tar éis 30 soicind, 2 nóiméad, 10 nóiméad, 30 nóiméad, 1 uair an chloig, 3 uair an chloig, 6 uair an chloig agus 12 uair an chloig, thart ar 24 uair an chloig san iomlán, sula marcáiltear an seachadadh martheipthe
• Seoltar gach seachadadh ag freastalaí amháin ag an am, agus mar sin ní sheolann rith roinnt samplaí API é faoi dhó

Fíoraigh x-nordlet-signature-v2 le comparáid ama-sheasmhach sula dtairgtear muinín san ualach íocaíochta, agus diúltaigh do sheachadadh a bhfuil a stampa ama níos mó ná 5 nóiméad ón do chlog. Is cuid den téacs sínithe é an stampa ama, agus mar sin ní féidir seachadadh gafa a athimirt níos déanaí le stampa ama nua. Stóráil na IDanna x-nordlet-delivery a phróiseáil tú chun neamhshuim a dhéanamh d'athrá laistigh den fhuinneog sin. Is féidir seachadadh teipthe a sheoladh arís le webhooks/deliveries/redeliver.

Iniúchadh (Audit)

Taifeadtar gach só-ghníomh (actor, action, entity, diff) agus is féidir é a cheistiú trí audit/list.

Ráthaíochtaí cuntasaíochta

• Tá postálacha irise cothromaithe - feidhmithe le truicear bunachar sonraí i gcur siar ag am tiomanta, ní hamháin trí chód feidhmchláir.
• Tá uimhreacha doiciméid saor ó bhearnaí in aghaidh na sraithe/na bliana; tá leithdháileadh sábháilte ar chomhuaineacht.
• Diúltaíonn tréimhse chuntasaíochta ghlasáilte d'aon phostáil a bhfuil dátaistrithe taobh istigh di (409).
• Coinníonn doiciméid scriosta go bog a n-rian iniúchta; ní féidir doiciméid eisithe/cláraithe a scriosadh.