Pradžia

Nordlet yra pirmiausia API (API-first) principu pagrįsta buhalterinės apskaitos platforma, skirta ES/EEE rinkai, pradedanti veiklą visiškai pritaikyta Lietuvos teisės aktams. Visos produkto funkcijos — sąskaitų faktūrų išrašymas, didžioji knyga, banko sąskaitų suderinimas (bank reconciliation), i.SAF — yra pasiekiamos per vieną JSON API.

1. Gaukite API raktą

Kiekviena užklausa yra autentifikuojama naudojant Bearer API raktą, priskirtą vienai įmonei (scoped to one company):

Authorization: Bearer nl_...

Vietiniam kūrimui (local development) inicijuokite įmonę ir raktą:

pnpm --filter @nordlet/db bootstrap:dev     # empty company
pnpm --filter @nordlet/api seed:demo        # company with demo data

Interaktyvi API dokumentacija (OpenAPI specifikacija pasiekiama /openapi.json; vietinė instancija (local instance) pateikia tą pačią dokumentaciją adresu http://localhost:3001/docs).

Postman

Labiau patinka Postman? Importuokite paruoštą kolekciją — visi galiniai punktai (endpoints), sugrupuoti pagal modulius, su iš anksto sukonfigūruotu „bearer“ autentifikavimu: Nordlet Postman collection. Importavę, bearerToken kintamajam priskirkite savo API raktą ir kiekviena užklausa bus automatiškai autentifikuojama.

Smėliadėžės (sandbox) įmonės

Integracijų testavimui sukurkite įmonę su parametru isSandbox: true (POST /v1/account/companies/create arba programėlėje pažymėkite smėliadėžės varnelę registracijos metu). Smėliadėžės įmonė veikia lygiai taip pat, kaip tikra — tie patys moduliai, tas pats API, todėl per ją galite apdoroti realistiškas operacijų (transactions) apimtis. Tačiau ji yra aiškiai pažymėta kaip testiniai duomenys, o ją ištrynus viskas pašalinama nedelsiant, vietoje įprasto 10 dienų duomenų saugojimo laikotarpio. Vienoje paskyroje šalia tikros įmonės galite turėti neribotą skaičių smėliadėžės įmonių; sukūrus įmonę šis požymis tampa nekeičiamas, todėl tikri apskaitos registrai (real books) niekada negali būti nepastebimai perklasifikuoti į testinius duomenis.

2. Pirmosios užklausos

Kiekviena operacija yra POST /v1/{module}/{resource}/{action} su JSON formato užklausos kūnu (body). Sukurkite pirkėją:

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"}'

Išrašykite sąskaitą faktūrą (sumos pateikiamos dešimtainiais skaičiais teksto eilutės (string) formatu, niekada kaip slankiojo kablelio (float) skaičiai):

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"}'

Išrašant priskiriamas nenutrūkstamas eilės numeris (SF-1), patikrinama, ar apskaitos periodas atviras, ir toje pačioje transakcijoje užregistruojamas subalansuotas dvejybinis įrašas (balanced journal entry) (D 2410 pirkėjų įsiskolinimas / K 5001 pajamos / K 4492 PVM).

3. Visas ciklas

Žingsnis	Užklausa
Perkelti apskaitą iš ankstesnės sistemos	migration/books/validate → migration/books/import — žr. Perkėlimas iš kitos sistemos
Užregistruoti tiekėjo sąskaitą faktūrą	purchases/invoices/create → purchases/invoices/register
Importuoti banko išrašą	bank/statements/import (camt.053 XML) arba bank/transactions/import (JSON)
Gauti sudengimo pasiūlymus	bank/transactions/suggest-matches
Sudengti mokėjimą	bank/transactions/match — užregistruoja mokėjimą ir atnaujina paymentStatus
Apmokėti tiekėjams	bank/payments/export — pain.001 SEPA failas jūsų bankui
Mėnesiniai PVM registrai	declarations/lt/isaf/generate — i.SAF 1.2 XML failas VMI
PVM deklaracijos rodikliai	declarations/lt/fr0600/compute — FR0600 laukeliai, suderinti su registrais
Išsiųsti prekes su važtaraščiu	transport/waybills/create → issue, tada declarations/lt/ivaz/generate — i.VAZ XML failas VMI

4. TypeScript SDK

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}`),
})

SDK generuojamas iš tiesioginės (live) OpenAPI specifikacijos (pnpm --filter @nordlet/sdk generate), todėl kiekvienos užklausos ir atsakymo tipai yra griežtai apibrėžti (fully typed).

5. „Webhooks“

Prenumeruokite įvykius, užuot periodiškai siuntę užklausas (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"]}'

Pristatomi pranešimai (deliveries) turi HMAC parašą (x-nordlet-signature: sha256=<hex> sugeneruotą iš neapdoroto užklausos kūno (raw body) ir jūsų prenumeratos paslapties (secret)), o nepavykus pristatyti, jie kartojami taikant eksponentinį uždelsimą (exponential backoff).

Dabartiniai įvykiai: sale_invoice.issued, sale_invoice.paid, purchase_invoice.registered, purchase_invoice.paid.

Žr. API konvencijos norėdami sužinoti apie sąrašų užklausas (list queries), klaidų formatus (error envelopes), idempotentiškumo semantiką ir užklausų limitus (rate limits).