Darba sākšana

Nordlet ir API orientēta grāmatvedības platforma ES/EEZ tirgum, kas tiek palaista ar pilnu atbilstību Lietuvas normatīvajiem aktiem. Visas produkta iespējas - rēķinu izrakstīšana, virsgrāmata (general ledger), bankas kontu saskaņošana, i.SAF - ir pieejamas, izmantojot vienu JSON API.

1. Saņemiet API atslēgu

Katrs pieprasījums tiek autentificēts, izmantojot Bearer API atslēgu, kas piesaistīta vienam uzņēmumam:

Authorization: Bearer nl_...

Vietējai izstrādei sagatavojiet uzņēmumu un atslēgu:

pnpm --filter @nordlet/db bootstrap:dev     # tukšs uzņēmums
pnpm --filter @nordlet/api seed:demo        # uzņēmums ar demo datiem

Interaktīva API atsauce (OpenAPI specifikācija atrodas /openapi.json; vietējā instance nodrošina to pašu atsauci adresē http://localhost:3001/docs).

Postman

Dodat priekšroku Postman? Importējiet gatavo kolekciju - katrs galapunkts (endpoint), sagrupēts pa moduļiem, ar iepriekš iestatītu bearer autentifikāciju: Nordlet Postman kolekcija. Pēc importēšanas iestatiet kolekcijas mainīgo bearerToken uz savu API atslēgu, un katrs pieprasījums tiks autentificēts.

Smilšu kastes (sandbox) uzņēmumi

Integrācijas testēšanai izveidojiet uzņēmumu ar iestatījumu isSandbox: true (POST /v1/account/companies/create vai atzīmējiet smilšu kastes izvēles rūtiņu reģistrācijas laikā lietotnē). Smilšu kastes uzņēmums darbojas precīzi tāpat kā īsts uzņēmums - tie paši moduļi, tas pats API, lai jūs varētu caur to novadīt reālistisku transakciju apjomu -, taču tas ir skaidri marķēts kā testa dati, un tā dzēšana visu izdzēš nekavējoties, nevis pēc 10 dienu saglabāšanas termiņa. Zem viena konta varat palaist jebkuru skaitu smilšu kastes uzņēmumu līdzās savam reālajam uzņēmumam; šī pazīme pēc izveides nav maināma, tāpēc reālos grāmatvedības datus nekad nevar nejauši pārklasificēt par testa datiem. Lietošana smilšu kastes uzņēmumā tiek uzskaitīta un rēķināta precīzi tāpat kā lietošana reālā uzņēmumā: pieprasījumi, dokumentu skenēšanas lapas, krātuve un atkārtotas aktivizācijas maksa. Smilšu kastes uzņēmuma atskaites un e-rēķini vienmēr tiek nosūtīti uz administrācijas testa galapunktiem.

2. Pirmie pieprasījumi

Katra operācija ir POST /v1/{module}/{resource}/{action} ar JSON pamattekstu (body). Izveidojiet klientu (partneri):

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

Izrakstiet rēķinu (summas ir decimāldaļas virknēs, nekad peldošā komata skaitļ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"}'

Izrakstīšana piešķir secīgu numuru bez pārtraukumiem (SF-1), pārbauda, vai grāmatvedības periods ir atvērts, un tajā pašā transakcijā iegrāmato sabalansētu grāmatojumu (D 2410 debitori / C 5001 ieņēmumi / C 4492 PVN).

3. Pilns cikls

Darbība	Izsaukums
Pārnest grāmatvedības datus no iepriekšējās sistēmas	migration/books/validate → migration/books/import - skatiet sadaļu Migrēšana no citas sistēmas
Reģistrēt piegādātāja rēķinu	purchases/invoices/create → purchases/invoices/register
Importēt bankas konta izrakstu	bank/statements/import (camt.053 XML) vai bank/transactions/import (JSON)
Saņemt sakritību ieteikumus	bank/transactions/suggest-matches
Saskaņot maksājumu	bank/transactions/match - iegrāmato maksājumu un atjaunina paymentStatus
Maksāt piegādātājiem	bank/payments/export - pain.001 SEPA fails jūsu bankai
Ikmēneša PVN reģistri	declarations/lt/isaf/generate - i.SAF 1.2 XML VID
PVN deklarācijas rādītāji	declarations/lt/fr0600/compute - FR0600 lauki, kas saskaņoti ar reģistriem
Piegādāt preces ar pavadzīmi	transport/waybills/create → issue, pēc tam declarations/lt/ivaz/generate - i.VAZ XML VID

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 tiek ģenerēts no tiešsaistes OpenAPI specifikācijas (pnpm --filter @nordlet/sdk generate), tāpēc katrs pieprasījums un atbilde ir pilnībā tipizēti.

5. Tīmekļa āķi (Webhooks)

Abonējiet notikumus, tā vietā lai veiktu aptauju (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"]}'

Piegādātie dati ietver ar laika zīmogu apzīmētu HMAC parakstu (x-nordlet-signature-v2: t=<unix seconds>,v1=<hex>, aprēķinātu no <timestamp>.<raw body>, izmantojot jūsu abonementa noslēpumu) blakus sākotnējam neapstrādātā pamatteksta parakstam x-nordlet-signature: sha256=<hex>, un to piegāde tiek atkārtota aptuveni 24 stundas. Informāciju par atkārtotas nosūtīšanas logu skatiet sadaļā API konvencijas.

Katrs piegādātais pamatteksts ir { id, version, companyId, eventType, createdAt, data }: version ir aploksnes versija (pašlaik 1) un companyId ir uzņēmums, kuram pieder notikums, tāpēc viens uztvērējs var apkalpot vairākus uzņēmumus. Abonēšana uz nosaukumu, kas nav norādīts tālāk sniegtajā sarakstā, tiek noraidīta ar statusu 400; izmantojiet "*" visiem notikumiem. Ja 5 notikumus pēc kārtas neizdevās piegādāt, abonements tiek apturēts un uzņēmuma īpašnieki saņem e-pastu; to var atkārtoti aktivizēt sadaļā Account → Webhooks vai izmantojot webhooks/subscriptions/update un isActive: true.

Notikumi: 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. OpenAPI dokumentā katrs no tiem ir norādīts sadaļā x-webhooks.

Informāciju par saraksta pieprasījumiem, kļūdu aploksnēm, idempotences semantiku un pieprasījumu skaita ierobežojumiem (rate limits) skatiet sadaļā API konvencijas.