Erste Schritte

Nordlet ist eine API-first-Buchhaltungsplattform für den EU/EWR-Markt, die zum Start die vollständige Compliance für Litauen bietet. Alle Funktionen des Produkts — Rechnungsstellung, Hauptbuch (General Ledger), Bankabgleich, i.SAF — stehen über eine einzige JSON-API zur Verfügung.

1. API-Schlüssel abrufen

Jede Anfrage wird mit einem Bearer-API-Schlüssel authentifiziert, der auf ein einziges Unternehmen beschränkt ist:

Authorization: Bearer nl_...

Für die lokale Entwicklung können Sie ein Unternehmen und einen Schlüssel initialisieren (bootstrap):

pnpm --filter @nordlet/db bootstrap:dev     # empty company
pnpm --filter @nordlet/api seed:demo        # company with demo data

Interaktive API-Referenz (OpenAPI-Spezifikation unter /openapi.json; eine lokale Instanz stellt dieselbe Referenz unter http://localhost:3001/docs bereit).

Postman

Bevorzugen Sie Postman? Importieren Sie die vorgefertigte Collection — jeder Endpunkt, gruppiert nach Modulen, mit vorkonfigurierter Bearer-Authentifizierung: Nordlet Postman collection. Setzen Sie nach dem Import die Variable bearerToken der Collection auf Ihren API-Schlüssel, und jede Anfrage wird automatisch authentifiziert.

Sandbox-Unternehmen

Erstellen Sie für Integrationstests ein Unternehmen mit isSandbox: true (POST /v1/account/companies/create, oder aktivieren Sie das Sandbox-Kontrollkästchen während des Onboardings in der App). Ein Sandbox-Unternehmen verhält sich exakt wie ein echtes Unternehmen — gleiche Module, gleiche API, sodass Sie realistische Transaktionsvolumina darüber abwickeln können. Es ist jedoch deutlich als Testdaten gekennzeichnet, und beim Löschen werden alle Daten sofort und nicht erst nach der 10-tägigen Aufbewahrungsfrist endgültig entfernt. Sie können beliebig viele Sandbox-Unternehmen neben Ihrem echten Unternehmen unter demselben Konto betreiben; das Flag ist nach der Erstellung unveränderlich, sodass echte Bücher niemals stillschweigend als Testdaten umklassifiziert werden können. Die Nutzung in einem Sandbox-Unternehmen wird exakt so gemessen und abgerechnet wie in einem echten Unternehmen: Anfragen, Seiten für das Scannen von Dokumenten, Speicherplatz und die Reaktivierungsgebühr.

2. Erste Aufrufe

Jede Operation ist ein POST /v1/{module}/{resource}/{action} mit einem JSON-Body. Einen Kunden anlegen:

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

Eine Rechnung ausstellen (Beträge sind Dezimal-Strings, niemals 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"}'

Bei der Ausstellung wird eine lückenlose Rechnungsnummer (SF-1) vergeben, geprüft, ob die Buchungsperiode offen ist, und der ausgeglichene Buchungssatz (S 2410 Forderungen / H 5001 Umsatzerlöse / H 4492 Umsatzsteuer) in derselben Transaktion verbucht.

3. Der vollständige Zyklus

Schritt	Aufruf
Die Bücher aus einem vorherigen System übernehmen	migration/books/validate → migration/books/import — siehe Migration aus einem anderen System
Eine Eingangsrechnung (supplier bill) erfassen	purchases/invoices/create → purchases/invoices/register
Einen Kontoauszug importieren	bank/statements/import (camt.053 XML) oder bank/transactions/import (JSON)
Abgleichsvorschläge abrufen	bank/transactions/suggest-matches
Eine Zahlung abgleichen	bank/transactions/match — verbucht die Zahlung und aktualisiert paymentStatus
Lieferanten bezahlen	bank/payments/export — pain.001 SEPA-Datei für Ihre Bank
Monatliche Umsatzsteuerregister	declarations/lt/isaf/generate — i.SAF 1.2 XML für VMI
Kennzahlen der Umsatzsteuervoranmeldung	declarations/lt/fr0600/compute — FR0600-Felder, abgestimmt mit den Registern
Waren mit einem Frachtbrief versenden	transport/waybills/create → issue, dann declarations/lt/ivaz/generate — i.VAZ XML für 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}`),
})

Das SDK wird aus der Live-OpenAPI-Spezifikation generiert (pnpm --filter @nordlet/sdk generate), sodass jede Anfrage und Antwort vollständig typisiert ist.

5. Webhooks

Abonnieren Sie Ereignisse, anstatt sie durch Polling abzufragen:

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

Zustellungen enthalten eine HMAC-Signatur (x-nordlet-signature: sha256=<hex> des rohen Bodys mit Ihrem Abonnement-Geheimnis) und werden bei Fehlern mit exponentiellem Backoff erneut versucht.

Aktuelle Ereignisse: sale_invoice.issued, sale_invoice.paid, purchase_invoice.registered, purchase_invoice.paid.

Siehe API-Konventionen für Listenabfragen, Fehler-Envelopes, Idempotenz-Semantik und Rate Limits.