Alustamine

Nordlet on API-keskne raamatupidamisplatvorm EL-i ja EMP turule, mis tuleb turule täieliku Leedu nõuetele vastavusega. Kõik toote funktsioonid – arveldamine, pearaamat, pangakontode sobitamine (bank reconciliation), i.SAF – on kättesaadavad üheainsa JSON API kaudu.

1. API võtme hankimine

Iga päring autentitakse Bearer API võtmega, mis on seotud ühe kindla ettevõttega:

Authorization: Bearer nl_...

Kohalikuks arenduseks looge ettevõte ja võti:

pnpm --filter @nordlet/db bootstrap:dev     # tühi ettevõte
pnpm --filter @nordlet/api seed:demo        # demoandmetega ettevõte

Interaktiivne API viide (OpenAPI spetsifikatsioon asub aadressil /openapi.json; kohalik instants pakub sama viidet aadressil http://localhost:3001/docs).

Postman

Eelistate Postmani? Importige valmis kollektsioon - iga otspunkt (endpoint), rühmitatuna moodulite kaupa ja eelhäälestatud bearer-autentimisega: Nordleti Postmani kollektsioon. Pärast importimist määrake kollektsiooni muutujale bearerToken oma API võti ja iga päring ongi autenditud.

Liivakasti ettevõtted (Sandbox companies)

Integratsioonitestimiseks looge ettevõte parameetriga isSandbox: true (POST /v1/account/companies/create või märkige rakenduse liitumisel ära liivakasti märkeruut). Liivakasti ettevõte käitub täpselt nagu päris ettevõte – samad moodulid, sama API, et saaksite selle kaudu suunata läbi realistliku tehingumahu –, kuid see on selgelt tähistatud testandmetena ja selle kustutamine eemaldab kõik koheselt, mitte alles 10-päevase säilitusperioodi möödudes. Saate käitada mis tahes arvu liivakasti ettevõtteid oma reaalse ettevõtte kõrval sama konto all; see lipp on pärast loomist muutmatu, mistõttu reaalset raamatupidamist ei saa kunagi märkamatult testandmeteks ümber klassifitseerida. Liivakasti ettevõtte kasutust mõõdetakse ja arveldatakse täpselt samamoodi nagu reaalse ettevõtte puhul: päringud, dokumentide skannimise leheküljed, salvestusruum ja taasaktiveerimistasu. Liivakasti ettevõtte aruanded ja e-arved lähevad alati ametiasutuste testotspunktidesse.

2. Esimesed päringud

Iga toiming on kujul POST /v1/{module}/{resource}/{action} koos JSON päringukehaga. Kliendi loomine:

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

Arve koostamine (summad on kümnendmurruna esitatud tekstistringid, mitte ujukomaarvud):

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

Arve esitamine omistab lünkadeta numbri (SF-1), kontrollib, et raamatupidamisperiood on avatud, ja kirjendab tasakaalus kande (D 2410 nõuded / C 5001 tulu / C 4492 käibemaks) sama tehingu raames.

3. Täielik tsükkel

Samm	Päring
Raamatupidamise üleviimine eelmisest süsteemist	migration/books/validate → migration/books/import - vaadake Migreerimine teisest süsteemist
Tarnija arve registreerimine	purchases/invoices/create → purchases/invoices/register
Pangaväljavõtte importimine	bank/statements/import (camt.053 XML) või bank/transactions/import (JSON)
Vastavussoovituste saamine	bank/transactions/suggest-matches
Makse sobitamine	bank/transactions/match - kirjendab makse ja uuendab välja paymentStatus
Tarnijatele tasumine	bank/payments/export - pain.001 SEPA fail teie pangale
Igakuised käibemaksuaruanded	declarations/lt/isaf/generate - i.SAF 1.2 XML Maksuametile (VMI)
Käibemaksudeklaratsiooni näitajad	declarations/lt/fr0600/compute - registritega võrreldud FR0600 väljad
Kauba saatmine saatelehega	transport/waybills/create → issue, seejärel declarations/lt/ivaz/generate - i.VAZ XML Maksuametile (VMI)

4. TypeScripti 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 genereeritakse otse reaalajas OpenAPI spetsifikatsioonist (pnpm --filter @nordlet/sdk generate), mistõttu on igal päringul ja vastusel täielik tüübikontroll.

5. Veebikonksud (Webhooks)

Tellige sündmused teadete pärimise (polling) asemel:

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

Edastused sisaldavad ajatempliga HMAC allkirja (x-nordlet-signature-v2: t=<unix seconds>,v1=<hex>, mis on arvutatud kujul <timestamp>.<raw body> koos teie tellimuse salajase võtmega), mis asub toorandmete algse allkirja x-nordlet-signature: sha256=<hex> kõrval, ning edastust korratakse umbes 24 tunni jooksul. Kordusvahemiku (replay window) kohta leiate lisateavet API kokkulepetest.

Iga edastuse sisu on kujul { id, version, companyId, eventType, createdAt, data }: version on ümbriku versioon (praegu 1) ja companyId on ettevõte, millele sündmus kuulub, nii et üks vastuvõtja saab teenindada mitut ettevõtet. Sellise nime tellimisest, mida allpool olevas loendis pole, keeldutakse veakoodiga 400; kasutage iga sündmuse jaoks tähist "*". Kui viit sündmust järjest ei õnnestu edastada, peatatakse tellimus ajutiselt ja ettevõtte omanikud saavad e-kirja; saate selle uuesti aktiveerida jaotises Konto → Veebikonksud (Account → Webhooks) või päringuga webhooks/subscriptions/update, seades väärtuseks isActive: true.

Sündmused: 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. OpenAPI dokument loetleb igaühe neist jaotises x-webhooks.

Loendipäringute, veaümbriste, identsuspäringute semantika (idempotency semantics) ja päringupiirangute (rate limits) kohta leiate lisateavet API kokkulepetest.