Noțiuni introductive

Chei API, primele apeluri, ciclul complet de facturare, SDK-uri și webhook-uri.

Nordlet este o platformă de contabilitate bazată pe API pentru piața din UE/SEE, lansată cu conformitate fiscală completă pentru Lituania. Tot ceea ce face produsul - facturare, carte mare (general ledger), reconciliere bancară, i.SAF - este disponibil printr-un singur API JSON.

1. Obținerea unei chei API

Fiecare cerere este autentificată cu o cheie API de tip Bearer alocată unei singure companii:

Authorization: Bearer nl_...

Pentru dezvoltare locală, inițializați o companie și o cheie:

pnpm --filter @nordlet/db bootstrap:dev     # companie goală
pnpm --filter @nordlet/api seed:demo        # companie cu date demonstrative

Referință API interactivă (specificația OpenAPI la /openapi.json; o instanță locală oferă aceeași referință la http://localhost:3001/docs).

Postman

Preferați Postman? Importați colecția gata făcută - fiecare punct final (endpoint), grupat pe module, cu autentificarea bearer preconfigurată: Colecția Nordlet Postman. După import, setați variabila bearerToken a colecției la cheia dumneavoastră API, iar fiecare cerere va fi autentificată.

Companii sandbox

Pentru testarea integrării, creați o companie cu isSandbox: true (POST /v1/account/companies/create sau bifați căsuța sandbox în timpul configurării inițiale în aplicație). O companie sandbox se comportă exact ca una reală - aceleași module, același API, astfel încât să puteți rula un volum realist de tranzacții prin ea -, dar este marcată vizibil ca date de test, iar ștergerea ei elimină totul imediat, nu după fereastra de retenție de 10 zile. Puteți rula oricâte companii sandbox alături de cea reală în același cont; fanionul este imutabil după creare, astfel încât registrele reale nu pot fi niciodată reclasificate în mod subtil ca date de test. Utilizarea într-o companie sandbox este contorizată și facturată exact la fel ca utilizarea într-o companie reală: cereri, pagini scanate de documente, stocare și taxa de reactivare. Declarațiile și e-facturile unei companii sandbox merg întotdeauna către punctele finale de test ale administrațiilor fiscale.

2. Primele apeluri

Fiecare operațiune este un apel POST /v1/{module}/{resource}/{action} cu un corp JSON. Creați un client (partner):

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

Emiteți o factură (sumele sunt șiruri zecimale, niciodată numere cu virgulă mobilă - floats):

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

Emiterea alocă un număr secvențial fără întreruperi (SF-1), verifică dacă perioada contabilă este deschisă și înregistrează nota contabilă echilibrată (D 2410 creanțe / C 5001 venituri / C 4492 TVA) în aceeași tranzacție.

3. Ciclul complet

Pas	Apel
Preluarea registrelor dintr-un sistem anterior	`migration/books/validate` → `migration/books/import` - consultați Migrarea dintr-un alt sistem
Înregistrarea unei facturi de la furnizor	`purchases/invoices/create` → `purchases/invoices/register`
Importul unui extras de cont	`bank/statements/import` (XML camt.053) sau `bank/transactions/import` (JSON)
Obținerea sugestiilor de potrivire	`bank/transactions/suggest-matches`
Reconcilierea unei plăți	`bank/transactions/match` - înregistrează plata și actualizează `paymentStatus`
Plata furnizorilor	`bank/payments/export` - fișier SEPA pain.001 pentru banca dumneavoastră
Jurnale lunare de TVA	`declarations/lt/isaf/generate` - XML i.SAF 1.2 pentru VMI
Cifrele pentru decontul de TVA	`declarations/lt/fr0600/compute` - câmpurile FR0600 reconciliate cu jurnalele
Livrarea de bunuri cu aviz de însoțire	`transport/waybills/create` → `issue`, apoi `declarations/lt/ivaz/generate` - XML i.VAZ pentru VMI

4. SDK pentru TypeScript

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-ul este generat din specificația OpenAPI în timp real (pnpm --filter @nordlet/sdk generate), astfel încât fiecare cerere și răspuns beneficiază de tipizare completă.

5. Webhook-uri

Abonați-vă la evenimente în loc să interogați periodic (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"]}'

Livrările conțin o semnătură HMAC marcată temporal (x-nordlet-signature-v2: t=<unix seconds>,v1=<hex> aplicată asupra <timestamp>.<raw body> folosind secretul abonamentului dumneavoastră) alături de vechea semnătură x-nordlet-signature: sha256=<hex> a corpului brut, iar reîncercările sunt efectuate timp de aproximativ 24 de ore. Consultați Convenții API pentru fereastra de retransmisie.

Fiecare corp de livrare este de forma { id, version, companyId, eventType, createdAt, data }: version este versiunea plicului (în prezent 1), iar companyId este compania căreia îi aparține evenimentul, astfel încât un singur receptor poate deservi mai multe companii. Abonarea la un nume care nu se află în lista de mai jos este respinsă cu codul 400; folosiți "*" pentru toate evenimentele. După 5 eșecuri consecutive de livrare, abonamentul este pus în pauză, iar administratorii companiei primesc un e-mail; reactivați-l din Cont (Account) → Webhook-uri sau prin webhooks/subscriptions/update cu isActive: true.

Evenimente: 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. Documentul OpenAPI listează fiecare eveniment în secțiunea x-webhooks.

Consultați Convenții API pentru interogări de liste, plicuri de eroare, semantica de idempotență și limitele de acces (rate limits).