Začíname

Nordlet je účtovná platforma založená na API pre trh EÚ/EHP, ktorá prichádza s plnou podporou legislatívy pre Litvu. Všetko, čo produkt dokáže - fakturácia, hlavná kniha (general ledger), párovanie platieb s bankou (bank reconciliation), i.SAF -, je dostupné prostredníctvom jedného JSON API.

1. Získanie kľúča API

Každá požiadavka sa autentifikuje pomocou Bearer kľúča API, ktorý sa viaže na konkrétnu spoločnosť:

Authorization: Bearer nl_...

Pre lokálny vývoj si môžete pripraviť spoločnosť a kľúč:

pnpm --filter @nordlet/db bootstrap:dev     # prázdna spoločnosť
pnpm --filter @nordlet/api seed:demo        # spoločnosť s demo údajmi

Interaktívna referenčná príručka API (špecifikácia OpenAPI je dostupná na adrese /openapi.json, pričom lokálna inštancia poskytuje rovnakú príručku na adrese http://localhost:3001/docs).

Postman

Uprednostňujete Postman? Importujte pripravenú kolekciu - obsahuje všetky koncové body zoskupené podľa modulov s prednastavenou bearer autentifikáciou: Kolekcia Nordlet pre Postman. Po importe nastavte premennú kolekcie bearerToken na váš kľúč API a každá požiadavka bude automaticky autentifikovaná.

Testovacie spoločnosti (Sandbox)

Na testovanie integrácie si vytvorte spoločnosť s príznakom isSandbox: true (POST /v1/account/companies/create, prípadne začiarknite políčko sandbox počas úvodnej registrácie v aplikácii). Testovacia spoločnosť funguje presne tak isto ako reálna - obsahuje rovnaké moduly a rovnaké API, takže cez ňu môžete prehnať realistický objem transakcií -, je však zreteľne označená ako testovacie údaje a jej vymazanie odstráni všetky dáta okamžite namiesto 10-dňovej lehoty na uchovanie. Pod jedným účtom môžete prevádzkovať ľubovoľný počet testovacích spoločností popri reálnej spoločnosti. Tento príznak sa po vytvorení nedá zmeniť, takže reálne účtovníctvo sa nikdy nemôže omylom preklasifikovať na testovacie údaje. Využívanie v testovacej spoločnosti sa meria a fakturuje úplne rovnako ako v reálnej spoločnosti: požiadavky, strany naskenovaných dokumentov, úložisko a poplatok za reaktiváciu. Výkazy a e-faktúry z testovacej spoločnosti smerujú vždy na testovacie koncové body úradov.

2. Prvé volania

Každá operácia má podobu POST /v1/{module}/{resource}/{action} s telom v JSON. Vytvorenie odberateľa (partnera):

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

Vystavenie faktúry (sumy sú desatinné reťazce, nikdy nie čísla s plávacou rádovou čiarkou):

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

Vystavenie faktúry priradí číslo bez medzier v číselnom rade (SF-1), skontroluje, či je účtovné obdobie otvorené, a v rámci tej istej transakcie zaúčtuje vyrovnaný účtovný zápis (MD 2410 pohľadávky / D 5001 výnosy / D 4492 DPH).

3. Kompletný cyklus

Krok	Volanie
Prenos účtovníctva z predchádzajúceho systému	migration/books/validate → migration/books/import - pozrite si Migrácia z iného systému
Zaevidovanie dodávateľskej faktúry	purchases/invoices/create → purchases/invoices/register
Import bankového výpisu	bank/statements/import (camt.053 XML) alebo bank/transactions/import (JSON)
Získanie návrhov na párovanie	bank/transactions/suggest-matches
Párovanie platby	bank/transactions/match - zaúčtuje platbu a aktualizuje stav paymentStatus
Úhrada dodávateľom	bank/payments/export - súbor pain.001 SEPA pre vašu banku
Mesačné výkazy DPH	declarations/lt/isaf/generate - i.SAF 1.2 XML pre daňový úrad
Údaje pre daňové priznanie k DPH	declarations/lt/fr0600/compute - položky FR0600 skontrolované voči kontrolným výkazom
Dodanie tovaru s prepravným lístkom	transport/waybills/create → issue, potom declarations/lt/ivaz/generate - i.VAZ XML pre daňový úrad

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

Sada SDK sa generuje zo živej špecifikácie OpenAPI (pnpm --filter @nordlet/sdk generate), takže každá požiadavka a odpoveď sú plne typované.

5. Webhooky

Prihláste sa na odber udalostí namiesto pravidelného dopytovania (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"]}'

Doručené správy obsahujú HMAC podpis s časovou pečiatkou (x-nordlet-signature-v2: t=<unix seconds>,v1=<hex> vypočítaný z reťazca <timestamp>.<raw body> pomocou tajného kľúča vášho odberu) popri pôvodnom hlavičkovom podpise x-nordlet-signature: sha256=<hex> surového tela správy. V prípade zlyhania sa doručenie opakuje približne 24 hodín. Informácie o okne na opätovné odoslanie nájdete v časti Konvencie API.

Telo každej doručenej správy má štruktúru { id, version, companyId, eventType, createdAt, data }: version označuje verziu obálky (aktuálne 1) a companyId identifikuje spoločnosť, ktorej sa udalosť týka, takže jeden koncový bod môže obsluhovať viacero spoločností. Prihlásenie na odber názvu udalosti, ktorý sa nenachádza v zozname nižšie, bude odmietnuté chybovým kódom 400; ak chcete odoberať všetky udalosti, použite *. Ak sa 5 udalostí za sebou nepodarí doručiť, odber sa pozastaví a vlastníci spoločnosti dostanú e-mailové upozornenie. Odber môžete obnoviť v časti Účet → Webhooky alebo pomocou koncového bodu webhooks/subscriptions/update s nastavením isActive: true.

Udalosti: 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 uvádza každú udalosť v časti x-webhooks.

Informácie o vyhľadávacích dopytoch, chybových obálkach, sémantike idempotencie a obmedzeniach počtu požiadaviek (rate limits) nájdete v časti Konvencie API.