Pradžia

Nordlet yra programėlėms skirta (API-first) apskaitos platforma, skirta ES / EEE rinkai, pradedanti veiklą su visišku atitikimu Lietuvos teisės aktams. Viskas, ką daro produktas - sąskaitų faktūrų išrašymas, didžioji knyga (general ledger), banko išrašų sudengimas (bank reconciliation), i.SAF - pasiekiama per vieną JSON API.

1. Gaukite API raktą

Kiekviena užklausos autorizacija atliekama naudojant Bearer API raktą, susietą su viena įmone:

Authorization: Bearer nl_...

Vietinei plėtrai paruoškite įmonę ir raktą:

pnpm --filter @nordlet/db bootstrap:dev     # tuščia įmonė
pnpm --filter @nordlet/api seed:demo        # įmonė su demonstraciniais duomenimis

Interaktyvi API žinynas (OpenAPI specifikacija pasiekiama per /openapi.json, o vietinis egzempliorius tą pačią nuorodą pateikia adresu http://localhost:3001/docs).

Postman

Pirmenybę teikiate Postman? Importuokite paruoštą rinkinį (collection): kiekvienas galutinis punktas (endpoint), sugrupuotas pagal modulius, su iš anksto nustatyta bearer autorizacija - Nordlet Postman rinkinys. Importavę nustatykite rinkinio kintamąjį bearerToken į savo API raktą, ir kiekviena užklausa bus autorizuota.

Smėlio dėžės įmonės (sandbox companies)

Integracijos testavimui sukurkite įmonę nustatydami isSandbox: true (POST /v1/account/companies/create arba programėlėje įstaškykite smėlio dėžės žymimąjį langelį registracijos metu). Smėlio dėžės įmonė veikia lygiai taip pat kaip tikra įmonė - tie patys moduliai, tas pats API, todėl per ją galite paleisti tikrovišką operacijų srautą - tačiau ji aiškiai pažymėta kaip bandomieji duomenys, o ją ištrynus viskas ištrinama nedelsiant, o ne pasibaigus 10 dienų saugojimo laikotarpiui. Pagal tą pačią paskyrą galite paleisti bet kokį smėlio dėžės įmonių skaičių šalia savo tikrosios įmonės; šio žymeklio po sukūrimo pakeisti negalima, todėl tikrųjų apskaitos knygų niekada nepavyks slapta priskirti bandomiesiems duomenims. Naudojimas smėlio dėžės įmonėje matuojamas ir apmokestinamas lygiai taip pat kaip ir tikroje įmonėje: užklausos, dokumentų nuskaitymo puslapiai, saugykla ir pakartotinio aktyvavimo mokestis.

2. Pirmosios užklausos

Kiekviena operacija yra POST /v1/{module}/{resource}/{action} su JSON pagrindiniu tekstu (body). Sukurkite verslo partnerį:

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 yra dešimtainiai eilutės formatu, jokių slankiojo kablelio skaičių):

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šymo metu priskiriamas nuoseklus numeris be tarpų (SF-1), patikrinama, ar apskaitos laikotarpis yra atviras, ir toje pačioje operacijoje įregistruojamas sabalansuotas žurnalo įrašas (D 2410 gautinos sumos / K 5001 pajamos / K 4492 PVM).

3. Visas ciklas

Žingsnis	Užklausa
Perkelti apskaitos knygas iš ankstesnės sistemos	migration/books/validate → migration/books/import - žr. Migravimas 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
Mokė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 VMI institucijai
PVM deklaracijos duomenys	declarations/lt/fr0600/compute - FR0600 laukai, sutikrinti su registrais
Gabenti prekes su važtaraščiu	transport/waybills/create → issue, tuomet declarations/lt/ivaz/generate - i.VAZ XML VMI institucijai

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 yra sugeneruotas iš tiesioginės OpenAPI specifikacijos (pnpm --filter @nordlet/sdk generate), todėl kiekviena užklausa ir atsakas yra visiškai tipizuoti.

5. Saistytieji elementai (Webhooks)

Užuot siuntę nuolatines užklausas (polling), prenumeruokite įvykius:

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

Pranešimuose perduodamas laiko žyma pažymėtas HMAC parašas (x-nordlet-signature-v2: t=<unix seconds>,v1=<hex>, apskaičiuotas pagal <timestamp>.<raw body> su jūsų prenumeratos paslaptimi) šalia pradinio gauto žaliavinio turinio parašo x-nordlet-signature: sha256=<hex>, o nesėkmės atveju siuntimas kartojamas apie 24 valandas. Informacijos apie pakartotinio siuntimo langą ieškokite skyriuje API susitarimai.

Kiekvieno pranešimo turinys yra { id, version, companyId, eventType, createdAt, data }: version yra voko versija (šiuo metu 1), o companyId yra įmonė, kuriai priklauso įvykis, todėl viena gavimo paslauga gali aptarnauti kelias įmones. Bandymas prenumeruoti pavadinimą, kurio nėra toliau pateiktame sąraše, bus atmstas grąžinant 400 klaidą; naudokite "*" visiems įvykiams prenumeruoti. Jei 5 įvykiai iš eilės nebuvo sėkmingai pristatyti, prenumerata pristabdoma, o įmonės savininkai gauna el. laišką; prenumeratą galite atnaujinti skiltyje Nustatymai (Settings) → Saistytieji elementai (Webhooks) arba iškvietę webhooks/subscriptions/update su nustatymu isActive: true.

Įvykiai: agreement.invoice_generated, bank_feed.synced, 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, 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_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. Kiekvienas iš jų OpenAPI dokumente pateikiamas skiltyje x-webhooks.

Informacijos apie sąrašų užklausas, klaidų vokus, pasikartojimo (idempotency) semantiką ir užklausų dažnio apribojimus (rate limits) ieškokite skyriuje API susitarimai.