Első lépések

API-kulcsok, első kérések, a teljes számlázási ciklus, SDK-k és webhookok.

A Nordlet egy API-központú könyvelési platform az EU/EGT piacon, amely teljes körű litvániai megfelelőséggel indul. A termék minden funkciója - számlázás, főkönyv, banki egyeztetés, i.SAF - egyetlen JSON API-n keresztül érhető el.

1. API-kulcs igénylése

Minden kérés hitelesítése egy adott vállalathoz rendelt Bearer API-kulccsal történik:

Authorization: Bearer nl_...

Helyi fejlesztéshez indítson el egy vállalatot és kulcsot:

pnpm --filter @nordlet/db bootstrap:dev     # üres vállalat
pnpm --filter @nordlet/api seed:demo        # vállalat demó adatokkal

Interaktív API-referencia (OpenAPI specifikáció a /openapi.json címen; egy helyi példány ugyanezt a referenciát a http://localhost:3001/docs címen szolgálja ki).

Postman

Jobban szereti a Postmant? Importálja az előre elkészített gyűjteményt - minden végpont modulok szerint csoportosítva, előre beállított Bearer hitelesítéssel: Nordlet Postman gyűjtemény. Az importálás után állítsa be a gyűjtemény bearerToken változóját az API-kulcsára, és minden kérés hitelesítve lesz.

Tesztkörnyezeti (sandbox) vállalatok

Integrációs teszteléshez hozzon létre egy vállalatot az isSandbox: true paraméterrel (POST /v1/account/companies/create, vagy jelölje be a tesztkörnyezet jelölőnégyzetét az alkalmazásban végzett regisztráció során). Egy tesztkörnyezeti vállalat pontosan úgy működik, mint egy igazi - ugyanazok a modulok, ugyanaz a JSON API, így reális tranzakciós volument küldhet át rajta -, de jól láthatóan tesztadatként van megjelölve, és a törlése a 10 napos megőrzési időszak helyett azonnal mindent eltávolít. Futtathat tetszőleges számú tesztkörnyezeti vállalatot a valós vállalat mellett ugyanazon fióken belül; a jelző a létrehozás után nem módosítható, így a valós könyvelési adatok soha nem minősíthetők át csendben tesztadatokká. Egy tesztkörnyezeti vállalat használata pontosan ugyanúgy van elszámolva és számlázva, mint egy valós vállalaté: kérések, dokumentumbeolvasási oldalak, tárhely és az újraintegrálási díj. A tesztkörnyezeti vállalat adóbevallásai és e-számlái mindig az adóhatóság tesztvégpontjaira futnak be.

2. Az első kérések

Minden művelet a POST /v1/{module}/{resource}/{action} formátumot használja JSON törzzsel. Hozzon létre egy partnert:

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

Állítson ki egy számlát (az összegek decimális sztringek, soha nem lebegőpontos számok):

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

A kiállítás egy résmentes sorszámot (SF-1) generál, ellenőrzi, hogy a könyvelési időszak nyitva van-e, és egy tranzakción belül könyveli az egyensúlyban lévő könyvelési tételt (T 2410 követelések / K 5001 árbevétel / K 4492 áfa).

3. A teljes ciklus

Lépés	Hívás
Könyvelési adatok átvétele egy korábbi rendszerből	`migration/books/validate` → `migration/books/import` - lásd Migrálás másik rendszerből
Szállítói számla rögzítése	`purchases/invoices/create` → `purchases/invoices/register`
Bankszámlakivonat importálása	`bank/statements/import` (camt.053 XML) vagy `bank/transactions/import` (JSON)
Párosítási javaslatok lekérése	`bank/transactions/suggest-matches`
Fizetés egyeztetése	`bank/transactions/match` - könyveli a fizetést és frissíti a `paymentStatus` mezőt
Szállítók kifizetése	`bank/payments/export` - pain.001 SEPA fájl a bankja számára
Havi áfa-nyilvántartások	`declarations/lt/isaf/generate` - i.SAF 1.2 XML a VMI számára
Áfa-bevallási adatok	`declarations/lt/fr0600/compute` - a nyilvántartásokkal egyeztetett FR0600 mezők
Áruk kiszállítása szállítólevéllel	`transport/waybills/create` → `issue`, majd `declarations/lt/ivaz/generate` - i.VAZ XML a VMI számára

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

Az SDK az éles OpenAPI specifikációból generálódik (pnpm --filter @nordlet/sdk generate), így minden kérés és válasz teljes mértékben típushelyes.

5. Webhookok

Feliratkozás az eseményekre lekérdezés (polling) helyett:

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

A kézbesítések az eredeti nyers törzs szerinti x-nordlet-signature: sha256=<hex> mellett egy időbélyeggel ellátott HMAC-aláírást (x-nordlet-signature-v2: t=<unix seconds>,v1=<hex> a <timestamp>.<raw body> tartalomra a feliratkozási titkos kulccsal) is tartalmaznak, és a rendszer kb. 24 órán keresztül ismétli a küldésüket. Az újrajátszási ablakról lásd az API-konvenciókat.

Minden kézbesítési törzs formátuma { id, version, companyId, eventType, createdAt, data }: a version a burkolt üzenet verziója (jelenleg 1), a companyId pedig az a vállalat, amelyhez az esemény tartozik, így egyetlen fogadó végpont több vállalatot is kiszolgálhat. Az alábbi listában nem szereplő névre történő feliratkozást a rendszer 400-as hibával elutasítja; minden eseményhez használja a "*" értéket. Ha 5 esemény egymás után nem kézbesíthető, a feliratkozás szünetel, és a vállalat tulajdonosai e-mailt kapnak; aktiválja újra a Fiók → Webhookok menüpontban vagy a webhooks/subscriptions/update hívással az isActive: true beállítással.

Események: 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. Az OpenAPI dokumentum minden egyes eseményt az x-webhooks alatt sorol fel.

A listalekérdezéseket, a hibaleíró burkolatokat, az idempotencia-szemantikát és a kéréskorlátokat (rate limits) lásd az API-konvenciókban.