Začetek uporabe

Nordlet je računovodska platforma, zasnovana okoli API-ja (API-first), namenjena trgu EU in EGP, ki se zaganja s popolno skladnostjo z litovsko zakonodajo. Vse, kar izdelek omogoča – izdajanje računov, glavna knjiga, usklajevanje bančnih izpiskov, i.SAF –, je na voljo prek enega samega JSON API-ja.

1. Pridobitev API ključa

Vsaka zahteva je overjena z API ključem tipa Bearer, ki je vezan na določeno podjetje:

Authorization: Bearer nl_...

Za lokalni razvoj zaženite začetno nastavitev podjetja in ključa:

pnpm --filter @nordlet/db bootstrap:dev     # prazno podjetje
pnpm --filter @nordlet/api seed:demo        # podjetje s predstavitvenimi podatki

Interaktivna referenca API-ja (specifikacija OpenAPI je na voljo na /openapi.json, lokalna instanca pa isto referenco ponuja na naslovu http://localhost:3001/docs).

Postman

Raje uporabljate Postman? Uvozite pripravljeno zbirko, kjer so vsi končne točke (endpoints), razporejeni po modulih, z vnaprej nastavljeno overitvijo Bearer: Nordletova zbirka za Postman. Po uvozu nastavite spremenljivko bearerToken v zbirki na svoj API ključ in vsaka zahteva bo samodejno overjena.

Testna okolja (sandbox)

Za testiranje integracije ustvarite podjetje z zastavico isSandbox: true (POST /v1/account/companies/create ali pa ob vklopu v aplikaciji označite potrditveno polje za testno okolje). Testno podjetje deluje povsem enako kot pravo – isti moduli, isti API, kar omogoča pošiljanje realističnega obsega transakcij –, vendar je jasno označeno kot testni podatki, njegov izbris pa vsebino takoj trajno odstrani namesto po 10-dnevnem obdobju hrambe. V okviru samega računa lahko vzporedno poganjate poljubno število testnih podjetij poleg pravega; zastavice po ustvarjanju ni mogoče spremeniti, zato se prave poslovne knjige nikoli ne morejo tiho preklasificirati v testne podatke. Uporaba v testnem podjetju se obračunava popolnoma enako kot v pravem podjetju: zahteve, strani za optično branje dokumentov, shramba in provizija za ponovno aktivacijo. Obračuni in e-računi testnega podjetja gredo vedno na testne končne točke davčnih organov.

2. Prvi klici

Vsaka operacija je zahteva tipa POST /v1/{module}/{resource}/{action} s telesom JSON. Ustvarite stranko:

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

Izdajte račun (zneski so nizi decimalk, nikoli plavajoče vejice):

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

Izdaja določi naslednjo zaporedno številko brez vrzeli (SF-1), preveri, ali je obračunsko obdobje odprto, ter v isti transakciji knjiži uravnoteženo temeljnico (D 2410 terjatve / K 5001 prihodki / K 4492 DDV).

3. Celoten cikel

Korak	Klic
Prenos poslovnih knjig iz prejšnjega sistema	migration/books/validate → migration/books/import – glejte razdelek Selitev iz drugega sistema
Vnos prejetega računa dobavitelja	purchases/invoices/create → purchases/invoices/register
Uvoz bančnega izpiska	bank/statements/import (camt.053 XML) ali bank/transactions/import (JSON)
Pridobitev predlogov za ujemanje	bank/transactions/suggest-matches
Uskladitev plačila	bank/transactions/match – knjiži plačilo in posodobi polje paymentStatus
Izplačilo dobaviteljem	bank/payments/export – datoteka pain.001 SEPA za vašo banko
Mesečne evidenca DDV	declarations/lt/isaf/generate – i.SAF 1.2 XML za davčni urad
Podatki za obračun DDV	declarations/lt/fr0600/compute – polja obrazca FR0600, usklajena z evidencami
Odprema blaga z dobavnico	transport/waybills/create → issue, nato declarations/lt/ivaz/generate – i.VAZ XML za davčni urad

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 je ustvarjen neposredno iz delujoče specifikacije OpenAPI (pnpm --filter @nordlet/sdk generate), zato imajo vse zahteve in odgovori v celoti določene podatkovne tipe.

5. Spletni kljukci (Webhooks)

Naročite se na dogodke namesto nenehnega poizvedovanja (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"]}'

Dostavljena sporočila vsebujejo časovno ožigosan podpis HMAC (x-nordlet-signature-v2: t=<unix seconds>,v1=<hex>, izračunan nad nizom <timestamp>.<raw body> z uporabo tajnega ključa vaše naročnine) poleg prvotnega podpisa x-nordlet-signature: sha256=<hex> surovega telesa. Poskusi dostave se ponavljajo približno 24 ur. Okno za ponovno predvajanje je opisano v razdelku Konvencije API-ja.

Telo vsakega poslanega sporočila je { id, version, companyId, eventType, createdAt, data }: version predstavlja različico ovojnice (trenutno 1), companyId pa označuje podjetje, ki mu dogodek pripada, kar omogoča, da en sam sprejemnik obdeluje več podjetij. Naročanje na dogodek, ki ni na spodnjem seznamu, je zavrnjeno z kodo napake 400; za vse dogodke uporabite "*". Če dostava 5 zaporednih dogodkov ni uspela, se naročnina začasno prekine, lastniki podjetja pa prejmejo e-sporočilo. Naročnino lahko ponovno vklopite v razdelku Račun → Spletni kljukci (Account → Webhooks) ali prek klica webhooks/subscriptions/update z nastavitvijo isActive: true.

Dogodki: 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. Dokument OpenAPI navaja vsakega posebej pod razdelkom x-webhooks.

Glejte Konvencije API-ja za poizvedbe s seznami, ovojnice napak, semantiko idempotence in omejitve pogostosti klicev (rate limits).