Fyrstu skrefin

Nordlet er bókhaldsvettvangur sem byggir á vefþjónustum (API-first) fyrir ESB/EES-markaðinn, og er í upphafi með fullt samræmi við litháískar reglur. Allt sem varan gerir – reikningagerð, fjárhagsbókhald, bankaafstemmingar, i.SAF – er aðgengilegt í gegnum eitt JSON API.

1. Fáðu þér aðgangslykil (API key)

Öll beiðni er auðkennd með Bearer aðgangslykli sem er bundinn við eitt fyrirtæki:

Authorization: Bearer nl_...

Fyrir staðbundna þróun skal ræsa upp fyrirtæki og lykil:

pnpm --filter @nordlet/db bootstrap:dev     # tómt fyrirtæki
pnpm --filter @nordlet/api seed:demo        # fyrirtæki með kynningargögnum

Gagnvirk API tilvísun (OpenAPI forskrift á /openapi.json; staðbundið tilvik birtir sömu tilvísun á http://localhost:3001/docs).

Postman

Viltu frekar nota Postman? Flyttu inn tilbúna safnið – sérhver endapunktur, flokkaður eftir einingum, með innbyggðri bearer-auðkenningu: Nordlet Postman safnið. Eftir innflutning skal stilla bearerToken breytu safnsins á aðgangslykilinn þinn og öll beiðni verður auðkennd.

Prófunarumhverfi (Sandbox fyrirtæki)

Fyrir samþættingarprófanir skal stofna fyrirtæki með isSandbox: true (POST /v1/account/companies/create, eða haka við prófunarreitinn við upphaf notkunar í forritinu). Sandbox fyrirtæki hegðar sér alveg eins og raunverulegt fyrirtæki – sömu einingar, sama API, þannig að þatı getur dælt í gegnum það raunhæfu viðskiptamagni – en það er merkt greinilega sem prófunargagn og eyðing þess hreinsar allt út strax í stað þess að bíða eftir 10 daga varðveislutímabilum. Þú getur keyrt hvaða fjölda sem er af sandbox fyrirtækjum samhliða því raunverulega undir sama aðgangi; fáninn er óbreytanlegur eftir stofnun, þannig að raunveruleg bókhaldsgögn geta aldrei óvart verið endurflokkuð sem prófunargögn. Notkun í sandbox fyrirtæki er mæld og reiknuð nákvæmlega eins og notkun í raunverulegu fyrirtæki: beiðnir, skannaríður skjala, geymsla og endurvirkjunargjald. Skilagreinar og rafrænir reikningar sandbox fyrirtækis fara ávallt á prófunarendapunkta yfirvalda.

2. Fyrstu köllin

Sérhver aðgerð er POST /v1/{module}/{resource}/{action} með JSON bráðabrigðagögnum. Stofna viðskiptavin:

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

Gefa út reikning (upphæðir eru tugabrotastrengir, aldrei fleytitölur):

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

Útgáfa úthlutar samfelldu númeri (SF-1), staðfestir að bókhaldstímabilið sé opið og bókar jafna færslu (D 2410 viðskiptakröfur / C 5001 tekjur / C 4492 VSK) í sömu færslu.

3. Allt ferlið

Skref	Kall
Flytja bækurnar yfir úr fyrra kerfi	migration/books/validate → migration/books/import - sjá Flutningur úr öðru kerfi
Skrá birgðareikning	purchases/invoices/create → purchases/invoices/register
Flytja inn bankayfirlit	bank/statements/import (camt.053 XML) eða bank/transactions/import (JSON)
Fá ábendingar um samsvörun	bank/transactions/suggest-matches
Afstemma greiðslu	bank/transactions/match - bókar greiðsluna og uppfærir paymentStatus
Greiða birgjum	bank/payments/export - pain.001 SEPA skrá fyrir bankann þinn
Mánaðarlegar VSK-skrár	declarations/lt/isaf/generate - i.SAF 1.2 XML fyrir VMI
Tölur fyrir VSK-skýrslu	declarations/lt/fr0600/compute - FR0600 reitir afstæmdir við skrárnar
Afhenda vörur með farmbréfi	transport/waybills/create → issue, síðan declarations/lt/ivaz/generate - i.VAZ XML fyrir 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}`),
})

Hugbúnaðarþróunarsettið er útbúið út frá virkri OpenAPI forskrift (pnpm --filter @nordlet/sdk generate), þannig að öll beiðni og svar eru fullrituð.

5. Vefslóðaviðburðir (Webhooks)

Gerast áskrifandi að viðburðum í stað þess að sækja upplýsingar reglulega:

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

Sendingar eru með tímastimplaðri HMAC undirskrift (x-nordlet-signature-v2: t=<unix seconds>,v1=<hex> yfir <timestamp>.<raw body> ásamt áskriftarlyklinum þínum) til hliðar við upphaflegu x-nordlet-signature: sha256=<hex> undirskrift hrára bolanna, og er reynt aftur í um það bil 24 klukkustundir. Sjá API-venjur fyrir endurspilunargluggann.

Hver sendingarbolur er { id, version, companyId, eventType, createdAt, data }: version er útgáfa umslagsins (núna 1) og companyId er fyrirtækið sem viðburðurinn tilheyrir, þannig að einn móttakari getur þjónað several fyrirtækjum. Að gerast áskrifandi að nafni sem er ekki á listanum hér að neðan er hafnað með 400; notaðu "*" fyrir hvern einasta viðburð. Eftir að 5 viðburðir í röð náðu ekki að skila sér er áskriftinni stöðvað tímabundið og eigendur fyrirtækisins fá tölvupóst; endurræstu hana í Reikningur → Vefslóðaviðburðir (Account → Webhooks) eða með webhooks/subscriptions/update og isActive: true.

Viðburðir: 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 skjalið telur upp hvern og einn undir x-webhooks.

Sjá API-venjur fyrir listarspurningar, villuumsveip, eiginleika ítrekunarleysis (idempotency) og takmarkanir á tíðni beiðna (rate limits).