Začínáme

Nordlet je účetní platforma postavená na API pro trh EU a EHP, která přichází na trh s plnou podporou litevské legislativy. Vše, co produkt dokáže, tedy fakturace, hlavní kniha (general ledger), párování plateb (bank reconciliation) a výkazy i.SAF, je dostupné prostřednictvím jediného JSON API.

1. Získání API klíče

Každý požádek se ověřuje pomocí Bearer API klíče, který je vázán na konkrétní účetní jednotku:

Authorization: Bearer nl_...

Pro lokální vývoj můžete inicializovat firmu a klíč pomocí příkazů:

pnpm --filter @nordlet/db bootstrap:dev     # prázdná firma
pnpm --filter @nordlet/api seed:demo        # firma s demo daty

K dispozici je interaktivní reference API (specifikace OpenAPI se nachází na adrese /openapi.json; lokální instance poskytuje stejnou referenci na adrese http://localhost:3001/docs).

Postman

Preferujete Postman? Importujte připravenou kolekci, která obsahuje všechny koncové body rozdělené do modulů a předem nastavenou autorizaci: Kolekce Nordlet pro Postman. Po importu nastavte proměnnou kolekce bearerToken na hodnotu vašeho API klíče a všechny požadavky budou automaticky ověřovány.

Testovací prostředí (sandbox)

Pro integrační testování vytvořte firmy s příznakem isSandbox: true (pomocí POST /v1/account/companies/create nebo zaškrtnutím políčka sandbox během úvodního nastavení v aplikaci). Sandboxová firma se chová naprosto stejně jako ostrá – má stejné moduly a stejné API, takže přes ni můžete protlačit realistický objem transakcí –, je však zřetelně označena jako testovací data a její smazání proběhne okamžitě namísto deseti-denní lhůty pro uchování dat. V rámci jednoho účtu můžete provozovat libovolný počet sandboxových firem vedle své ostré firmy. Tento příznak nelze po vytvoření změnit, takže ostré účetní knihy nemohou být nikdy omylem přeřazeny mezi testovací data. Využití v sandboxové firmě se měří a fakturuje naprosto stejně jako v ostré firmě: počítají se požadavky, stránky naskenovaných dokumentů, úložiště a poplatek za reaktivaci. Hlášení a elektronické faktury sandboxové firmy směřují vždy na testovací koncové body úřadů.

2. První volání

Každá operace probíhá metodou POST /v1/{module}/{resource}/{action} s tělem ve formátu JSON. Vytvoření odběratele (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"}'

Vystavení faktury (částky se uvádějí jako řetězce s desetinnou tečkou, nikdy jako desetinná čísla s plovoucí řádkou):

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

Vystavení faktury přidělí číslo bez mezer v číselné řadě (SF-1), ověří, že účetní období je otevřené, a v rámci jedné transakce zaúčtuje vyrovnaný účetní zápis (MD 2410 pohledávky / D 5001 tržby / D 4492 DPH).

3. Kompletní cyklus

Krok	Volání
Přenastavení účetnictví z předchozího systému	`migration/books/validate` → `migration/books/import` – viz Migrace z jiného systému
Zaevidování přijaté faktury	`purchases/invoices/create` → `purchases/invoices/register`
Import bankovního výpisu	`bank/statements/import` (formát camt.053 XML) nebo `bank/transactions/import` (JSON)
Získání návrhů na spárování	`bank/transactions/suggest-matches`
Párování platby	`bank/transactions/match` – zaúčtuje platbu a aktualizuje pole `paymentStatus`
Úhrada dodavatelům	`bank/payments/export` – soubor SEPA pain.001 pro vaši banku
Měsíční registry DPH	`declarations/lt/isaf/generate` – i.SAF 1.2 XML pro litevský daňový úřad (VMI)
Podklady pro přiznání k DPH	`declarations/lt/fr0600/compute` – položky formuláře FR0600 odsouhlasené s registry
Vyskladnění zboží s dodacím listem	`transport/waybills/create` → `issue`, poté `declarations/lt/ivaz/generate` – i.VAZ XML pro VMI

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 generuje přímo z aktuální specifikace OpenAPI (pnpm --filter @nordlet/sdk generate), takže každý požadavek i odpověď jsou plně typované.

5. Webhooky

Místo pravidelného dotazování (polling) můžete odebírat oznámení o událostech:

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é zprávy obsahují časově opatřený podpis HMAC (x-nordlet-signature-v2: t=<unix seconds>,v1=<hex> vypočítaný z řetězce <timestamp>.<raw body> pomocí tajného klíče vaší odběratelské sady) vedle původního hlavičkového podpisu x-nordlet-signature: sha256=<hex> celého těla zprávy. Neúspěšná doručení se opakují přibližně 24 hodin. Podrobnosti o okně pro opětovné odeslání najdete v části Konvence API.

Tělo každé doručené zprávy má strukturu { id, version, companyId, eventType, createdAt, data }: version označuje verzování obálky (aktuálně 1) a companyId identifikuje firmu, které se událost týká, takže jeden koncový bod může obsluhovat více firem. Přihlášení k odběru názvu události, který není uveden v seznamu níže, bude odmítnuto chybou 400. Pro odběr všech událostí použijte *". Pokud se událost nepodaří doručit pětkrát za sebou, odběr se pozastaví a vlastníci firmy obdrží e-mailové upozornění. Odběr můžete znovu aktivovat v sekci Účet → Webhooky nebo pomocí volání webhooks/subscriptions/update s parametrem isActive: true.

Seznam událostí: 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. Dokumentace OpenAPI uvádí každou z nich v sekci x-webhooks.

Informace o filtrování seznamů, chybových obálkách, sémantice idempotence a limitech požadavků (rate limits) najdete v části Konvence API.