Nordlet

← Documentazione / Guide

Guida introduttiva

Chiavi API, prime chiamate, ciclo di fatturazione completo, SDK e webhook.

Nordlet è una piattaforma di contabilità API-first per il mercato UE/SEE, lanciata con piena conformità alla normativa lituana. Tutte le funzionalità del prodotto, dalla fatturazione al libro mastro (general ledger), dalla riconciliazione bancaria a i.SAF, sono accessibili tramite un'unica API JSON.

1. Ottenere una chiave API

Ogni richiesta viene autenticata tramite una chiave API Bearer associata a una singola azienda:

Authorization: Bearer nl_...

Per lo sviluppo locale, è possibile inizializzare un'azienda e una chiave:

pnpm --filter @nordlet/db bootstrap:dev     # azienda vuota
pnpm --filter @nordlet/api seed:demo        # azienda con dati dimostrativi

Riferimento API interattivo (specifica OpenAPI disponibile su /openapi.json; un'istanza locale offre lo stesso riferimento all'indirizzo http://localhost:3001/docs).

Postman

Preferisci usare Postman? Importa la collezione pronta all'uso, con ogni endpoint raggruppato per modulo e autenticazione bearer preconfigurata: Collezione Postman di Nordlet. Dopo l'importazione, imposta la variabile bearerToken della collezione con la tua chiave API e ogni richiesta verrà autenticata.

Aziende sandbox

Per i test di integrazione, crea un'azienda con isSandbox: true (POST /v1/account/companies/create, oppure seleziona la casella di controllo sandbox durante la configurazione iniziale nell'applicazione). Un'azienda sandbox si comporta esattamente come un'azienda reale, disponendo degli stessi moduli e delle stesse API per consentire l'invio di volumi di transazioni realistici, ma è chiaramente contrassegnata come dato di test e la sua eliminazione cancella tutto immediatamente anziché dopo il periodo di conservazione di 10 giorni. È possibile gestire un numero qualsiasi di aziende sandbox insieme a quella reale nell'ambito dello stesso account; il flag non è modificabile dopo la creazione, impedendo quindi che i dati contabili reali vengano riclassificati silenziosamente come dati di test. L'utilizzo in un'azienda sandbox viene misurato e fatturato esattamente come in un'azienda reale: richieste, pagine scansionate di documenti, spazio di archiviazione e costo di riattivazione. Le dichiarazioni e le fatture elettroniche di un'azienda sandbox vengono sempre inviate agli endpoint di test delle amministrazioni fiscali.

2. Prime chiamate

Ogni operazione consiste in una richiesta POST /v1/{module}/{resource}/{action} con un corpo JSON. Creazione di un cliente (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"}'

Emissione di una fattura (gli importi sono stringhe decimali, mai numeri in virgola mobile):

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

L'emissione assegna un numero progressivo senza interruzioni (SF-1), verifica che il periodo contabile sia aperto e registra la scrittura contabile bilanciata (Dare conto crediti commerciali 2410 / Avere conto ricavi 5001 / Avere conto IVA a debito 4492) nella stessa transazione.

3. Il ciclo completo

Fase Chiamata
Trasferimento della contabilità da un sistema precedente migration/books/validate → migration/books/import - vedi Migrazione da un altro sistema
Registrazione della fattura di un fornitore purchases/invoices/create → purchases/invoices/register
Importazione di un estratto conto bancario bank/statements/import (XML camt.053) o bank/transactions/import (JSON)
Ottenere suggerimenti di abbinamento bank/transactions/suggest-matches
Riconciliazione di un pagamento bank/transactions/match - registra il pagamento e aggiorna lo stato di pagamento (paymentStatus)
Pagamento ai fornitori bank/payments/export - file SEPA pain.001 per la banca
Registri IVA mensili declarations/lt/isaf/generate - XML i.SAF 1.2 per l'ispettorato fiscale (VMI)
Dati per la dichiarazione IVA declarations/lt/fr0600/compute - campi FR0600 riconciliati con i registri
Spedizione di merci con documento di trasporto transport/waybills/create → issue, quindi declarations/lt/ivaz/generate - XML i.VAZ per l'ispettorato fiscale (VMI)

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

L'SDK viene generato a partire dalla specifica OpenAPI in tempo reale (pnpm --filter @nordlet/sdk generate), pertanto ogni richiesta e risposta è completamente tipizzata.

5. Webhook

Iscriviti agli eventi invece di effettuare il 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"]}'

Le consegne includono una firma HMAC con timestamp (x-nordlet-signature-v2: t=<unix seconds>,v1=<hex> calcolata su <timestamp>.<raw body> utilizzando la chiave segreta di sottoscrizione) accanto alla firma originale x-nordlet-signature: sha256=<hex> del corpo grezzo, e vengono ripetute per circa 24 ore in caso di mancata consegna. Consulta le Convenzioni API per la finestra temporale di riproducibilità.

Il corpo di ogni consegna ha la struttura { id, version, companyId, eventType, createdAt, data }: version rappresenta la versione del wrapper (attualmente 1) e companyId è l'azienda a cui appartiene l'evento, consentendo a un unico ricevitore di gestire più aziende. La sottoscrizione a un nome evento non presente nell'elenco sottostante viene rifiutata con un errore 400; usa "*" per sottoscrivere tutti gli eventi. Se non è possibile consegnare 5 eventi consecutivi, la sottoscrizione viene sospesa e i titolari dell'azienda ricevono un'e-mail; è possibile riattivarla nella sezione Account → Webhook oppure tramite webhooks/subscriptions/update impostando isActive: true.

Eventi: 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. Il documento OpenAPI elenca ciascuno di essi alla voce x-webhooks.

Consulta le Convenzioni API per le query sugli elenchi, i wrapper di errore, la semantica di idempotenza e i limiti di frequenza (rate limit).