Početak rada

API ključevi, prvi pozivi, cijeli ciklus izdavanja računa, SDK-ovi i webhoookovi.

Nordlet je računovodstvena platforma usmjerena na API (API-first) za tržište EU-a i EGP-a, a pokreće se s potpunom usklađenošću s litavskim propisima. Sve što proizvod može – izdavanje računa, glavna knjiga (general ledger), usklađivanje bankovnih izvoda (bank reconciliation), i.SAF – dostupno je putem jednog JSON API-ja.

1. Dobivanje API ključa

Svaki se zahtjev autentificira Bearer API ključem koji je vezan uz jednu tvrtku:

Authorization: Bearer nl_...

Za lokalni razvoj možete inicijalizirati tvrtku i ključ:

pnpm --filter @nordlet/db bootstrap:dev     # prazna tvrtka
pnpm --filter @nordlet/api seed:demo        # tvrtka s demo podacima

Interaktivna API referenca (OpenAPI specifikacija nalazi se na adresi /openapi.json; lokalna instanca nudi istu referencu na http://localhost:3001/docs).

Postman

Preferirate Postman? Uvezite gotovu zbirku – svaki je krajnja točka (endpoint), grupirana po modulima, s unaprijed postavljenom bearer autentifikacijom: Nordlet Postman zbirka. Nakon uvoza, postavite varijablu zbirke bearerToken na svoj API ključ i svaki će zahtjev biti autentificiran.

Testne okoline (sandbox tvrtke)

Za testiranje integracije stvorite tvrtku s parametrom isSandbox: true (POST /v1/account/companies/create ili označite testnu kućicu (sandbox checkbox) tijekom početnog podešavanja u aplikaciji). Testna tvrtka ponaša se potpuno isto kao i stvarna – isti moduli, isti API, tako da kroz nju možete provoditi realan volumen transakcija – ali je jasno označena kao testni podatak, a njezino brisanje uklanja sve podatke odmah umjesto nakon razdoblja čuvanja od 10 dana. Unutar istog računa možete pokrenuti bilo koji broj testnih tvrtki uz svoju stvarnu tvrtku. Oznaka se nakon stvaranja više ne može mijenjati, čime se osigurava da se stvarne poslovne knjige (books) nikada ne mogu tiho preklasificirati u testne podatke. Korištenje u testnoj tvrtki mjeri se i naplaćuje na isti način kao i korištenje u stvarnoj tvrtki: zahtjevi, stranice za skeniranje dokumenata, pohrana i naknada za reaktivaciju. Prijave i e-računi testne tvrtke uvijek se šalju na testne krajnje točke nadležnih institucija.

2. Prvi pozivi

Svaka je operacija POST /v1/{module}/{resource}/{action} s JSON tijelom (body). Stvaranje kupca ili dobavljača (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"}'

Izdavanje računa (iznosi su decimalni nizovi znakova, nikada s pomičnom zarezom (floats)):

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

Izdavanjem se dodjeljuje broj bez praznina (SF-1), provjerava je li obračunsko razdoblje otvoreno te se u istoj transakciji knjiži uravnotežena temeljnica (D 2410 potraživanja / C 5001 prihodi / C 4492 PDV).

3. Cijeli ciklus

Korak	Poziv
Prijenos poslovnih knjiga iz prethodnog sustava	`migration/books/validate` → `migration/books/import` - pogledajte Migracija iz drugog sustava
Evidentiranje ulaznog računa dobavljača	`purchases/invoices/create` → `purchases/invoices/register`
Uvoz bankovnog izvoda	`bank/statements/import` (camt.053 XML) ili `bank/transactions/import` (JSON)
Dohvaćanje prijedloga za usklađivanje	`bank/transactions/suggest-matches`
Usklađivanje plaćanja	`bank/transactions/match` - knjiži plaćanje i ažurira status plaćanja (`paymentStatus`)
Isplata dobavljačima	`bank/payments/export` - pain.001 SEPA datoteka za vašu banku
Mjesečni PDV registri	`declarations/lt/isaf/generate` - i.SAF 1.2 XML za poreznu upravu
Podaci za prijavu PDV-a	`declarations/lt/fr0600/compute` - polja obrasca FR0600 usklađena s registrima
Otprema robe uz otpremnicu	`transport/waybills/create` → `issue`, zatim `declarations/lt/ivaz/generate` - i.VAZ XML za poreznu upravu

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 se generira iz aktivne OpenAPI specifikacije (pnpm --filter @nordlet/sdk generate), stoga su svaki zahtjev i odgovor u potpunosti tipizirani.

5. Webhookovi

Pretplatite se na događaje umjesto slanja upita (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"]}'

Isporuke sadrže HMAC potpis s vremenskom oznakom (x-nordlet-signature-v2: t=<unix seconds>,v1=<hex> preko <timestamp>.<raw body> s tajnim ključem vaše pretplate) uz izvorni x-nordlet-signature: sha256=<hex> sirovog tijela (raw body), a pokušaji slanja ponavljaju se otprilike 24 sata. Pogledajte API konvencije za prozor ponovnog slanja (replay window).

Svako tijelo isporuke ima oblik { id, version, companyId, eventType, createdAt, data }: version je verzija omotnice (trenutačno 1), a companyId je tvrtka kojoj događaj pripada, tako da jedan primatelj može opsluživati više tvrtki. Pretplata na naziv koji se ne nalazi na popisu u nastavku odbija se s kodom 400; koristite "*" za sve događaje. Nakon što se 5 događaja zaredom ne uspije isporučiti, pretplata se pauzira, a vlasnici tvrtke dobivaju e-poruku. Ponovno je aktivirajte u odjeljku Račun → Webhookovi (Account → Webhooks) ili putem poziva webhooks/subscriptions/update s parametrom isActive: true.

Događaji: 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 navodi svaki od njih pod odjeljkom x-webhooks.

Pogledajte API konvencije za upite popisa, omotnice pogrešaka, semantiku idempotencije i ograničenja stope poziva (rate limits).