Ag tosach

Is ardán cuntasaíochta é Nordlet atá bunaithe ar API (API-first) do mhargadh an Aontais Eorpaigh agus an Limistéar Eorpach Eacnamaíoch, agus é ag seoladh le comhlíonadh iomlán dhlí na Liotuáine. Tá gach rud a dhéanann an táirge - sonrascadh, an t-ardleabhar ginearálta (general ledger), réiteach bainc (bank reconciliation), i.SAF - ar fáil trí aon API JSON amháin.

1. Faigh eochair API

Déantar gach iarratas a fhíordheimniú le eochair Bearer API atá teoranta d'aon chuideachta amháin:

Authorization: Bearer nl_...

Chun forbairt áitiúil a dhéanamh, cuir cuideachta agus eochair ar bun:

pnpm --filter @nordlet/db bootstrap:dev     # cuideachta fhágach
pnpm --filter @nordlet/api seed:demo        # cuideachta le sonraí taispeána

Tagairt API idirghníomhach (sonraíocht OpenAPI ag /openapi.json; freastalaíonn cás áitiúil ar an tagairt chéanna ag http://localhost:3001/docs).

Postman

An fearr leat Postman? Iompórtáil an bailiúchán réamhdhéanta - gach críochphointe (endpoint), grúpáilte de réir modúil, le fíordheimniú bearer réamhchumraithe: Bailiúchán Postman Nordlet. Tar éis duit é a iompórtáil, socraigh athróg bearerToken an bhailiúcháin go dtí d'eochair API agus déantar gach iarratas a fhíordheimniú.

Cuideachtaí bosca qustaim (sandbox companies)

Chun tástáil comhtháthaithe a dhéanamh, cruthaigh cuideachta le isSandbox: true (POST /v1/account/companies/create, nó ticeáil an bosca seiceála bosca qustaim le linn an ailtireachta in aip). Caitheann cuideachta bosca qustaim díreach mar cuideachta réadach - na modúil céanna, an API céanna, ionas gur féidir leat méid réadach idirbheart a chur tríd - ach tá sé marcáilte go soiléir mar shonraí tástála agus scriostar gach rud láithreach nuair a scriostar é seachas tar éis an fhuinneoige coinneála 10 lá. Rith líon ar bith cuideachtaí bosca qustaim taobh le do chuideachta réadach faoin gcuntas céanna; ní féidir an bratach a athrú tar éis a cruthaithe, agus mar sin ní féidir leabhair réadach a aicmiú arís go ciúin mar shonraí tástála. Déantar tomhas agus billeáil ar úsáid i gcuideachta bosca qustaim go díreach mar a dhéantar d'úsáid i gcuideachta réadach: iarratais, leathanaigh scanta doiciméad, stóráil agus an táille athghníomhachtaithe. Téann comhdhúile agus ríomhshonrasc cuideachta bosca qustaim go dtí críochphointí tástála na n-iarscríbhinní riaracháin i gcónaí.

2. Na chéad ghlaonna

Is é gach oibríocht ná POST /v1/{module}/{resource}/{action} le comhlacht JSON. Cruthaigh custaiméir:

curl -X POST https://api.nordlet.com/v1/partners/create \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: partner-create-001" \
  -d '{"name": "UAB Klientas", "code": "301111222", "vatCode": "LT100001112223"}'

Eisigh sonrasc (is sreangáin deachúla iad méideanna, ná húsáid snámhphointí (floats) riamh):

curl -X POST https://api.nordlet.com/v1/sales/invoices/create \
  -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
  -d '{
    "partnerId": "<partner id>",
    "lines": [{"description": "Konsultacijos", "quantity": 4, "unitPriceExclVat": "75.0000", "vatClassifierCode": "PVM1"}]
  }'

curl -X POST https://api.nordlet.com/v1/sales/invoices/issue \
  -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
  -d '{"id": "<invoice id>", "issueDate": "2026-07-09"}'

Le linn an eisiúna, sannraítear uimhir gan bhearna (SF-1), seiceáiltear go bhfuil an tréimhse chuntasaíochta oscailte, agus postáiltear an iontráil irise comhchothromaithe (D 2410 fáltais / C 5001 ioncam / C 4492 CBL) san idirbheart céanna.

3. An timthriakal iomlán

Céim	Glao
Tabhair na leabhair anonn ó chóras roimhe seo	migration/books/validate → migration/books/import - féach ar Imirce ó chóras eile
Cláraigh sonrasc soláthraí	purchases/invoices/create → purchases/invoices/register
Iompórtáil ráiteas bainc	bank/statements/import (camt.053 XML) nó bank/transactions/import (JSON)
Faigh moltaí meaitseála	bank/transactions/suggest-matches
Réitigh íocaíocht	bank/transactions/match - postálann sé an íocaíocht agus déanann sé paymentStatus a nuashonrú
Íoc soláthraithe	bank/payments/export - comhad SEPA pain.001 do do bhanc
Cláir CBL mhíosúla	declarations/lt/isaf/generate - i.SAF 1.2 XML do VMI
Figiúirí tuairisceáin CBL	declarations/lt/fr0600/compute - réimsí FR0600 réitithe i gcoinne na gclár
Seol earraí le bille bealaigh	transport/waybills/create → issue, ansin declarations/lt/ivaz/generate - i.VAZ XML do VMI

4. SDK TypeScript

import { createNordletClient, idempotent } from '@nordlet/sdk'

const client = createNordletClient({
  baseUrl: 'https://api.nordlet.com',
  apiKey: process.env.NORDLET_API_KEY!,
})

const { data, error } = await client.POST('/v1/sales/invoices/create', {
  body: {
    partnerId,
    lines: [{ description: 'Konsultacijos', quantity: 4, unitPriceExclVat: '75.0000' }],
  },
  ...idempotent(`order-${orderId}`),
})

Gintear an SDK ón tsonraíocht bheo OpenAPI (pnpm --filter @nordlet/sdk generate), agus mar sin tá gach iarratas agus freagra clag-chlóscríofa go hiomlán.

5. Ríomhshuaitheanna (Webhooks)

Liostáil d'im EVENTS seachas vótáil (polling):

curl -X POST https://api.nordlet.com/v1/webhooks/subscriptions/create \
  -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/hooks/hyperion", "events": ["sale_invoice.issued", "sale_invoice.paid"]}'

Tá síniú HMAC le stampa ama ag gabháil le seachadtaí (x-nordlet-signature-v2: t=<unix seconds>,v1=<hex> thar <timestamp>.<raw body> le do rún síntiús) taobh le x-nordlet-signature: sha256=<hex> bunaidh an chomhlachta amh, agus déantar iad a athsheachadadh ar feadh thart ar 24 uair an chloig. Féach ar Coinbhinsiúin API don fhuinneog athimeara.

Is éard atá i gcomhlacht gach seachadta ná { id, version, companyId, eventType, createdAt, data }: is é version leagan an imchlúdaigh (faoi láthair 1) agus is é companyId an chuideachta lena mbaineann an t-imeacht, ionas gur féidir le glacadóir amháin freastal ar roinnt cuideachtaí. Diúltaítear le 400 má liostáiltear le hainm nach bhfuil sa liosta thíos; úsáid "*" do gach imeacht. Tar éis do 5 imeacht as a chéile gan seachadadh a bheith déanta, cuirtear an síntiús ar sos agus faigheann úinéirí na cuideachta ríomhphost; athghníomhaigh é in Account → Webhooks nó le webhooks/subscriptions/update agus isActive: true.

Imeachtaí: agreement.invoice_generated, bank_feed.synced, document_capture.peppol_received, filing.failed, filing.rejected, goods_receipt.posted, intercompany.invoice_mirrored, item.created, item.deleted, item.updated, lead.converted, lead.created, partner_inquiry.created, payroll_run.approved, payroll_run.reversed, pos_report.created, price_list.updated, purchase_invoice.paid, purchase_invoice.registered, purchase_order.approved, purchase_order.received, refund_liability.actual, refund_liability.trued_up, report.completed, report.failed, revenue_recognition.modified, revenue_recognition.posted, sale_invoice.einvoice_sent, sale_invoice.issued, sale_invoice.paid, sale_invoice.peppol_delivered, sale_invoice.peppol_failed, sale_invoice.peppol_rejected, sale_invoice.peppol_sent, sale_invoice.quote_sent, sale_invoice.sent, sales_order.created, sales_order.fulfilled, settlement.imported, settlement.posted, settlement.updated, stock.changed, stock.reorder_needed, vat_review.opened, vat_review.resolved. Liostaíonn an doiciméad OpenAPI gach ceann acu faoi x-webhooks.

Féach ar Coinbhinsiúin API le haghaidh iarratais liosta, imchlúdaigh earráide, séimeantaic aitíopúlachta, agus teorainneacha ráta (rate limits).