Bidu tal-bidu

Nordlet hija pjattaforma tal-kontabilità mfassla l-ewwel għall-API għas-suq tal-UE/ŻEE, li qed tnedi b'konformità sħiħa mal-liġijiet Litwani. Kull ħaġa li tagħmel il-pjattaforma – fatturazzjoni, ktieb ledger ġenerali, rikonċiljazzjoni bankarja, i.SAF – hija disponibbli permezz ta' API JSON waħda.

1. Akkwista ċ-ċavetta tal-API

Kull talba tiġi awtentikata b'ċavetta tal-API Bearer marbuta ma' kumpanija waħda:

Authorization: Bearer nl_...

Għall-iżvilupp lokali, tista' tistartja kumpanija u ċavetta:

pnpm --filter @nordlet/db bootstrap:dev     # kumpanija vojta
pnpm --filter @nordlet/api seed:demo        # kumpanija b'dejta ta' prova

Referenza interattiva tal-API (l-ispeċifikazzjoni OpenAPI tinsab fuq /openapi.json; istanza lokali tipprovdi l-istess referenza fuq http://localhost:3001/docs).

Postman

Tippreferi tuża Postman? Importa l-kollezzjoni lesta – kull endpoint, miġbur skont il-modulu, b'awtentikazzjoni bearer diġà kkonfigurata: Kollezzjoni Postman ta' Nordlet. Wara li timportaha, is-sett il-varjabbli bearerToken tal-kollezzjoni għċ-ċavetta tal-API tiegħek u kull talba tiġi awtentikata awtomatikament.

Kumpaniji Sandbox

Għall-ittestjar tal-integrazzjoni, oħloq kumpanija b'isSandbox: true (POST /v1/account/companies/create, jew immarka l-kaxxa sandbox waqt l-onboarding fl-applikazzjoni). Kumpanija sandbox iġġib ruħha eżattament bħal waħda reali – l-istess moduli, l-istess API, sabiex tkun tista' tgħaddi volum realistiku ta' tranżazzjonijiet minn ġo fiha – iżda tidher b'mod ċar bħala dejta tat-test u t-tħassir tagħha jneħħi kollox minnufih minflok wara l-perjodu ta' żamma ta' 10 ijiem. Tista' tħaddem kwalunkwe numru ta' kumpaniji sandbox flimkien mal-kumpanija reali tiegħek taħt l-istess kont; il-bandiera ma tistax tinbidel wara l-ħolqien, u b'hekk il-kotba reali qatt ma jistgħu jiġu kklassifikati mill-ġdid bħala dejta tat-test b'mod moħbi. L-użu f'kumpanija sandbox jitkejjel u jiġi fatturat eżattament bħall-użu f'kumpanija reali: it-talbiet, il-paġni tal-iskannjar tad-dokumenti, l-ispazju tal-ħażna u t-tariffa tar-reattivazzjoni. Id-dikjarazzjonijiet u l-e-fatturi ta' kumpanija sandbox dejjem jintbagħtu lejn l-endpoints tat-test tal-awtoritajiet.

2. L-ewwel sejħiet

Kull operazzjoni hija POST /v1/{module}/{resource}/{action} b'korp f'format JSON. Oħloq klijent:

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

Oħroġ fattura (l-ammonti huma kodiċi deċimali bħala kodiċi tat-test, qatt ma huma tip float):

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

Il-ħruġ ta' fattura jassenja numru sekwenzjali mingħajr lakuni (SF-1), jivverifika li l-perjodu tal-kontabilità huwa miftuħ, u jirreġistra d-dħul fil-ġurnal ibbilanċjat (D 2410 receivables / C 5001 revenue / C 4492 VAT) fl-istess tranżazzjoni.

3. Iċ-ċiklu sħiħ

Pass	Sejħa
Ittrasferixxi l-kotba minn sistema preċedenti	migration/books/validate → migration/books/import - ara Migrazzjoni minn sistema oħra
Reġistra fattura ta' fornitur	purchases/invoices/create → purchases/invoices/register
Importa estratt bankarju	bank/statements/import (camt.053 XML) jew bank/transactions/import (JSON)
Ikseb suġġerimenti ta' tqabbil	bank/transactions/suggest-matches
Rikonċilja pagament	bank/transactions/match - jirreġistra l-pagament u aġġorna paymentStatus
Ħallas lill-fornituri	bank/payments/export - fajl pain.001 SEPA għall-bank tiegħek
Reġistri tal-VAT mensili	declarations/lt/isaf/generate - i.SAF 1.2 XML għal VMI
Figuri tad-dikjarazzjoni tal-VAT	declarations/lt/fr0600/compute - oqsma tal-FR0600 rikonċiljati mar-reġistri
Ibgħat oġġetti b'nota tal-konsenja	transport/waybills/create → issue, imbagħad declarations/lt/ivaz/generate - i.VAZ XML għal 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}`),
})

L-SDK huwa ġenerat mill-ispeċifikazzjoni OpenAPI attiva (pnpm --filter @nordlet/sdk generate), għalhekk kull talba u tweġiba hija mfassla b'tipi sħaħ.

5. Webhooks

Abbona għall-avvenimenti minflok ma tibgħat talbiet ripetuti (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"]}'

Il-kunsinni jinkludu firma HMAC bi timbru tal-ħin (x-nordlet-signature-v2: t=<unix seconds>,v1=<hex> fuq <timestamp>.<raw body> bis-sigriet tas-subskrizzjoni tiegħek) flimkien mal-firma oriġinali x-nordlet-signature: sha256=<hex> tal-korp oriġinali, u jerġgħu jippruvaw jintbagħtu għal madwar 24 siegħa. Ara l-konvenzjonijiet tal-API għall-perjodu ta' trażmissjoni mill-ġdid.

Kull korp ta' kunsinna huwa { id, version, companyId, eventType, createdAt, data }: version hija l-verżjoni tal-pakkett (bħalissa 1) u companyId hija l-kumpanija li jappartjeni għaliha l-avveniment, sabiex riċevitur wieħed ikun jista' jaqdi diversi kumpaniji. Is-subskrizzjoni għal isem li ma jinsabx fil-lista t'hawn taħt tiġi miċħuda b'kodiċi 400; uża "*" għal kull avveniment. Wara 5 avvenimenti wara xulxin li ma setgħux jitwasslu, is-subskrizzjoni tiġi sospiża u s-sidien tal-kumpanija jirċievu email; tista' terġa' tattivaha f'Account → Webhooks jew permezz ta' webhooks/subscriptions/update u isActive: true.

Avvenimenti: 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. Id-dokument OpenAPI elenka kull wieħed taħt x-webhooks.

Ara l-konvenzjonijiet tal-API għal mistoqsijiet fuq listi, pakketti ta' żbalji, semantika tal-idempotenza, u limiti tar-rata ta' talbiet.